# GitLab CI/CD Quick Reference

## Quick Start

### 1. Initial Setup

```bash
# Clone repository
git clone https://gitlab.com/YOUR_USERNAME/mpv-manager.git
cd mpv-manager

# Ensure .gitlab-ci.yml is present
ls -la .gitlab-ci.yml
```

### 2. First Push

```bash
# Commit and push (triggers test pipeline)
git add .
git commit -m "Initial commit"
git push origin main
```

GitLab automatically runs:
- ✅ Tests on Linux
- ✅ Code coverage report

### 3. Create Release

```bash
# Tag release (triggers full build pipeline)
git tag v1.0.0
git push origin main
git push origin v1.0.0
```

GitLab automatically:
- ✅ Runs tests
- ✅ Builds all platforms (6 installers + 6 generators)
- ✅ Creates release packages
- ✅ Generates BLAKE3 checksums
- ✅ Creates GitLab release with all assets

---

## Workflow Examples

### Feature Development

```bash
# Create feature branch
git checkout -b feature/new-feature

# Make changes
vim cmd/mpv-manager/main.go

# Test locally
make test
make build

# Commit and push (triggers test pipeline)
git add .
git commit -m "Add new feature"
git push origin feature/new-feature
```

### Hotfix to Release

```bash
# Create hotfix branch from tag
git checkout -b hotfix/v1.0.1 v1.0.0

# Make fixes
vim pkg/version/version.go

# Test locally
make test
make build

# Commit and push
git add .
git commit -m "Fix critical bug"
git push origin hotfix/v1.0.1

# Merge to main via GitLab UI or git merge
git checkout main
git merge hotfix/v1.0.1

# Tag and release
git tag v1.0.1
git push origin main
git push origin v1.0.1
```

### Pre-release (Beta/RC)

```bash
# Tag as pre-release
git tag v1.1.0-beta.1
git push origin v1.1.0-beta.1
```

---

## Pipeline Status Commands

### Monitor Pipeline

```bash
# Open in browser
open https://gitlab.com/YOUR_USERNAME/mpv-manager/-/pipelines

# Or via CLI (requires gitlab-ci-local)
glab ci list
```

### View Logs

```bash
# View latest pipeline logs
open https://gitlab.com/YOUR_USERNAME/mpv-manager/-/pipelines/latest

# View specific job logs
open https://gitlab.com/YOUR_USERNAME/mpv-manager/-/jobs/JOB_ID
```

### Download Artifacts

```bash
# From GitLab UI
# CI/CD → Pipelines → Select Pipeline → Download Artifacts

# Or via API
curl --header "PRIVATE-TOKEN: YOUR_TOKEN" \
  "https://gitlab.com/api/v4/projects/PROJECT_ID/jobs/JOB_ID/artifacts"
```

---

## Common Scenarios

### Scenario 1: Build Fails

```bash
# Check pipeline logs
# CI/CD → Pipelines → Click on Failed Pipeline → Click on Failed Job

# Common fixes:
# - Add missing dependencies in build script
# - Fix syntax errors
# - Check environment variables
# - Verify ldflags syntax

# Rebuild (test pipeline only, no tag)
git commit --allow-empty -m "Trigger rebuild"
git push origin main
```

### Scenario 2: Tests Fail

```bash
# Run tests locally with verbose output
go test -v ./...

# Check coverage
go test -cover ./...

# Fix and commit
vim pkg/platform/cpu.go
git add .
git commit -m "Fix test failure"
git push origin main
```

### Scenario 3: Need Specific Build

```bash
# Only test stage
git commit --allow-empty -m "Test only"

# Only build stage (no test)
# Edit .gitlab-ci.yml to skip test, commit, then revert

# Build specific platform only
# Edit .gitlab-ci.yml, remove other jobs, commit, then revert
```

### Scenario 4: Update Version

```bash
# 1. Update version in code
vim pkg/version/version.go
# Change: const CurrentVersion = "1.0.1"

# 2. Commit changes
git add pkg/version/version.go
git commit -m "Bump version to 1.0.1"

# 3. Tag and push
git tag v1.0.1
git push origin main
git push origin v1.0.1
```

---

## Environment Variables

### Setting Custom Version

```bash
# Set via pipeline trigger in GitLab UI
# CI/CD → Pipelines → Run Pipeline → Add variable: VERSION=1.0.1

# Or set in .gitlab-ci.yml
variables:
  VERSION: "1.0.1"
```

### Sensitive Variables

```bash
# Set in GitLab UI (never commit to repo)
# Settings → CI/CD → Variables → Add Variable

# Examples:
# API_TOKEN=xxx (masked)
# AWS_ACCESS_KEY=xxx (masked)
# SSH_KEY=xxx (type: File)
```

---

## Branch Protection

### Recommended Protection Rules

```bash
# GitLab UI: Settings → Repository → Protected Branches

# Protect main branch:
# - Developers can push
# - Maintainers can merge
# - Require approval from 1 maintainer

# Protect tags:
# - Only maintainers can create tags
# - Only maintainers can push tags
```

---

## Release Checklist

Before tagging a release:

- [ ] All tests pass locally (`make test`)
- [ ] Build succeeds locally (`make build`)
- [ ] Cross-platform builds work (`make build-all`)
- [ ] CHANGELOG.md updated with release notes
- [ ] Version bumped in pkg/version/version.go
- [ ] No uncommitted changes
- [ ] Main branch is up to date

Creating the release:

```bash
# Tag release
git tag -a v1.0.0 -m "Release v1.0.0"

# Push tags
git push origin main
git push origin v1.0.0

# Monitor pipeline
open https://gitlab.com/YOUR_USERNAME/mpv-manager/-/pipelines
```

After release:

- [ ] Verify release created in GitLab
- [ ] Download and test binaries from release
- [ ] Verify BLAKE3 checksums
- [ ] Announce release to users
- [ ] Update documentation
- [ ] Create hotfix branch if needed

---

## Troubleshooting

### Pipeline Not Triggered

```bash
# Check .gitlab-ci.yml exists
ls -la .gitlab-ci.yml

# Verify YAML syntax
python3 -c "import yaml; yaml.safe_load(open('.gitlab-ci.yml'))"

# Check GitLab runner status
# GitLab UI: Settings → CI/CD → Runners
```

### Artifacts Expired

```bash
# Build artifacts: 7 days (not preserved)
# Release artifacts: 30 days (preserved in release)

# To preserve permanently:
# 1. Download release assets
# 2. Store in external location
# 3. Or use GitLab Package Registry
```

### Release Not Created

```bash
# Check tag format (must be like v1.0.0)
git tag -l

# Verify tag pushed
git push --tags --dry-run
git push origin v1.0.0

# Check release job logs
# CI/CD → Pipelines → Select Pipeline → release job
```

---

## CI/CD Dashboard

### Monitor All Pipelines

```bash
# Latest pipelines
open https://gitlab.com/YOUR_USERNAME/mpv-manager/-/pipelines

# Latest schedules (if configured)
open https://gitlab.com/YOUR_USERNAME/mpv-manager/-/pipeline_schedules

# All environments (if configured)
open https://gitlab.com/YOUR_USERNAME/mpv-manager/-/environments
```

### Pipeline Analytics

```bash
# View statistics
open https://gitlab.com/YOUR_USERNAME/mpv-manager/-/pipelines/charts

# See:
# - Success rate
# - Duration trends
# - Build frequency
```

---

## Advanced Tips

### Speed Up Builds

```yaml
# Add caching to .gitlab-ci.yml
variables:
  GOPATH: $CI_PROJECT_DIR/.go

cache:
  paths:
    - .go/pkg/mod/
    - vendor/
```

### Parallel Execution

All build jobs already run in parallel. To speed up:

- Use GitLab runners with more CPU
- Enable Docker runner autoscaling
- Use dedicated runners for builds

### Manual Approval

```yaml
# Require approval for release stage
release:
  stage: release
  when: manual  # Must click to run
  allow_failure: false
```

### Scheduled Builds

```yaml
# GitLab UI: CI/CD → Schedules → New Schedule
# Run tests daily at midnight
# Branch: main
# Cron: 0 0 * * *
```

---

## Quick Commands

```bash
# Run tests locally
make test

# Build locally
make build

# Build all platforms
make build-all

# Clean build artifacts
make clean

# Create release
git tag v1.0.0 && git push origin v1.0.0

# View pipeline
open https://gitlab.com/YOUR_USERNAME/mpv-manager/-/pipelines

# View releases
open https://gitlab.com/YOUR_USERNAME/mpv-manager/-/releases

# Download release
wget https://gitlab.com/YOUR_USERNAME/mpv-manager/-/releases/v1.0.0/downloads/mpv-manager-v1.0.0-linux-amd64.tar.gz
```

---

## Support

- **Documentation**: `docs/GITLAB_CI.md`
- **Makefile**: `Makefile`
- **Pipeline Config**: `.gitlab-ci.yml`
- **GitLab CI Docs**: https://docs.gitlab.com/ee/ci/