# GitLab CI/CD Pipeline Documentation

## Overview

The `.gitlab-ci.yml` file provides a comprehensive CI/CD pipeline for the MPV.Rocks Installer that:

1. **Runs tests** on every commit
2. **Builds binaries** for all platforms and architectures
3. **Creates release packages** (tar.gz for Linux/macOS, zip for Windows)
4. **Generates BLAKE3 checksums** for all release files
5. **Creates GitLab releases** with all binaries and documentation

## Pipeline Stages

```
test → build → checksum → release
```

### Stage: `test`

**Job:** `test:linux`
- Runs all Go tests with race detection
- Generates code coverage reports
- Runs on Docker with latest Go version
- Triggers on every commit

### Stage: `build`

**Installer Binaries:**
- `build:linux-amd64` - Linux x86_64
- `build:linux-arm64` - Linux ARM64
- `build:windows-x86_64` - Windows x86_64 (with GOAMD64=v2)
- `build:windows-arm64` - Windows ARM64
- `build:macos-intel` - macOS x86_64 (Intel)
- `build:macos-arm` - macOS ARM64 (Apple Silicon)

**Generator Binaries:**
- `build:generator-linux-amd64` - Linux x86_64
- `build:generator-linux-arm64` - Linux ARM64
- `build:generator-windows-x86_64` - Windows x86_64
- `build:generator-windows-arm64` - Windows ARM64
- `build:generator-macos-intel` - macOS x86_64
- `build:generator-macos-arm64` - macOS ARM64

**Checksums Binary:**
- `build:checksums` - gen-checksums tool

**All build jobs:**
- Inject version, build time, and git commit via ldflags
- Use static builds (CGO_ENABLED=0)
- Save artifacts for 7 days
- Run in parallel for faster execution

### Stage: `checksum`

**Packaging Jobs:**
- `package:linux` - Creates tar.gz packages for Linux installers
- `package:windows` - Creates zip packages for Windows installers
- `package:macos` - Creates tar.gz packages for macOS installers
- `package:generator` - Creates packages for all generators

**Checksums Job:**
- `checksums` - Runs gen-checksums to generate BLAKE3SUMS.txt
- Computes checksums for all packaged files
- Outputs in format: `blake3:hash  filename`

### Stage: `release`

**Job:** `release`
- **Only runs when a tag is pushed** (e.g., `git tag v1.0.0 && git push origin v1.0.0`)
- Creates GitLab release with:
  - Release notes and installation instructions
  - All installer binaries (6 files)
  - All generator binaries (6 files)
  - BLAKE3SUMS.txt for verification
- Uses GitLab Package Registry for asset storage

## Version Management

### Version Priority

The pipeline uses the following priority for versioning:

1. **Tag Version** (highest): `v1.0.0` → `VERSION=1.0.0`
2. **Default Version** (fallback): `1.0.0-dev` for non-tagged builds

### Creating a Release

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

The pipeline will:
1. Build all binaries with version `1.0.0`
2. Create release packages
3. Generate BLAKE3 checksums
4. Create GitLab release `v1.0.0`

### Version in Binary

```bash
$ ./mpv-manager --version
MPV.Rocks Installer
Version: 1.0.0
Build Time: 2026-02-06T11:47:42Z
Git Commit: 49d5620
```

## Build Artifacts

### Installer Binaries

| Platform | Architecture | File | Format | Size |
|----------|---------------|-------|---------|------|
| Linux | AMD64 | `mpv-manager-1.0.0-linux-amd64.tar.gz` | tar.gz | ~15MB |
| Linux | ARM64 | `mpv-manager-1.0.0-linux-arm64.tar.gz` | tar.gz | ~15MB |
| Windows | x86_64 | `mpv-manager-1.0.0-win-x86_64.zip` | zip | ~15MB |
| Windows | ARM64 | `mpv-manager-1.0.0-win-arm64.zip` | zip | ~15MB |
| macOS | Intel | `mpv-manager-1.0.0-macos-intel.zip` | zip | ~15MB |
| macOS | ARM | `mpv-manager-1.0.0-macos-arm.zip` | zip | ~15MB |

**Note:** Generator binaries are NOT included in releases. They're built by CI for internal use only.

### Checksums

- **BLAKE3SUMS.txt** - BLAKE3 hashes for all release files

## Usage

### Running Tests

Tests run automatically on every push. To run locally:

```bash
make test
# or
go test -v ./...
```

### Building Locally

```bash
# Build for current platform
make build

# Build for all platforms
make build-all

# Build with specific version
VERSION=1.0.1 make build
```

### Triggering a Release

```bash
# 1. Update version in version.go (if needed)
vim pkg/version/version.go

# 2. Commit changes
git add pkg/version/version.go
git commit -m "Release v1.0.0"

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

The GitLab pipeline will:
1. Run tests
2. Build all binaries
3. Create release packages
4. Generate checksums
5. Create GitLab release

### Downloading Releases

From GitLab UI:
1. Go to **Deployments → Releases**
2. Click on the desired release tag
3. Download the appropriate package

From command line:
```bash
# Example: Linux AMD64
wget https://gitlab.com/YOUR_USERNAME/YOUR_PROJECT/-/releases/v1.0.0/downloads/mpv-manager-v1.0.0-linux-amd64.tar.gz
tar -xzf mpv-manager-v1.0.0-linux-amd64.tar.gz
sudo mv mpv-manager-linux-amd64 /usr/local/bin/mpv-manager
```

### Verifying Checksums

```bash
# Download release and checksums
wget https://gitlab.com/YOUR_USERNAME/YOUR_PROJECT/-/releases/v1.0.0/downloads/mpv-manager-v1.0.0-linux-amd64.tar.gz
wget https://gitlab.com/YOUR_USERNAME/YOUR_PROJECT/-/releases/v1.0.0/downloads/BLAKE3SUMS.txt

# Install b3sum if not available
cargo install b3sum
# or
go install github.com/oconnormorris/b3sum@latest

# Verify
b3sum -c BLAKE3SUMS.txt
```

## Configuration

### Go Version

Default Go version: `1.25`

To change:
```yaml
variables:
  GO_VERSION: "1.25"
```

### Artifact Expiration

Default: 7 days for build artifacts, 30 days for release artifacts

### GitLab Runner Tags

Required: `docker` tag

Ensure your runners are configured with this tag:
```bash
gitlab-runner register \
  --tag-list "docker" \
  --executor docker
```

## Troubleshooting

### Build Fails with "CGO_ENABLED=0"

If your build needs CGO, remove `CGO_ENABLED=0` from the build commands.

### Release Not Created

1. Check that the tag follows semantic versioning: `v1.0.0`, `v1.1.0`, etc.
2. Verify the tag was pushed: `git push origin v1.0.0`
3. Check GitLab CI/CD → Pipelines for errors

### Checksums Don't Match

1. Ensure you're using the correct b3sum version
2. Check that the file wasn't corrupted during download
3. Verify the BLAKE3SUMS.txt file is complete

### Build Artifacts Expired

Build artifacts expire after 7 days by default. Release artifacts (from the release job) are preserved. If you need build artifacts:
1. Download them before expiration
2. Change `expire_in` in `.gitlab-ci.yml`

## Advanced Usage

### Custom Build Tags

To trigger builds with custom tags:

```bash
git commit --allow-empty -m "Trigger build"
git push origin main
```

### Manual Pipeline Trigger

From GitLab UI:
1. Go to **CI/CD → Pipelines**
2. Click **Run Pipeline**
3. Choose branch and variables

### Caching Dependencies

To speed up builds, add Go module caching:

```yaml
.go-cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - .go/pkg/mod/
    - .go/bin/
```

## CI/CD Variables

| Variable | Default | Description |
|-----------|----------|-------------|
| `BINARY_NAME` | `mpv-manager` | Main binary name |
| `GENERATOR_NAME` | `generate-info` | Generator binary name |
| `CHECKSUMS_NAME` | `gen-checksums` | Checksums binary name |
| `VERSION` | Tag or `1.0.0-dev` | Version to build |
| `GO_VERSION` | `1.25` | Go compiler version |
| `BUILD_TIME` | Pipeline timestamp | Build timestamp |
| `GIT_COMMIT` | Short commit hash | Git commit SHA |

## Security Considerations

1. **Tag Protection**: Protect release tags to prevent accidental overwrites
2. **Branch Protection**: Require approval for main branch changes
3. **Secret Variables**: Store sensitive data in CI/CD variables
4. **Checksums**: Always verify checksums before using downloaded binaries

## Best Practices

1. **Always tag releases** - Don't release from branches
2. **Update CHANGELOG.md** before tagging
3. **Test locally** before pushing tags
4. **Use semantic versioning** (v1.0.0, v1.0.1, v2.0.0)
5. **Keep releases small** - Don't bundle unnecessary files
6. **Document breaking changes** in release notes

## Integration with GitLab Registry

The pipeline can be extended to upload packages to GitLab Package Registry:

```bash
# After checksums stage, upload packages
curl --header "JOB-TOKEN: $CI_JOB_TOKEN" \
  --upload-file dist/mpv-manager-1.0.0-linux-amd64.tar.gz \
  "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/mpv-manager/1.0.0/mpv-manager-1.0.0-linux-amd64.tar.gz"
```

## Support

For issues or questions:
1. Check GitLab CI/CD → Pipelines for logs
2. Review `.gitlab-ci.yml` syntax
3. Consult GitLab CI/CD documentation: https://docs.gitlab.com/ee/ci/