unifi-network-operator/CICD.md

CI/CD Pipeline Documentation

This document describes the continuous integration and deployment pipeline for the UniFi Network Operator.

Overview

The CI/CD pipeline is built using GitHub Actions and provides:

• Automated testing on every pull request
• Multi-architecture Docker image builds (amd64, arm64)
• Automated Helm chart releases to GitHub Pages
• Complete release automation with version tagging
• Public Docker images via GitHub Container Registry

Quick Start

For Users

Install the operator using Helm:

# Add the Helm repository
helm repo add unifi-network-operator https://vegardengen.github.io/unifi-network-operator
helm repo update

# Install
helm install unifi-network-operator unifi-network-operator/unifi-network-operator \
  --namespace unifi-network-operator-system \
  --create-namespace \
  --set unifi.url="https://your-unifi-controller:8443" \
  --set unifi.password="your-password"

Or use Docker directly:

docker pull ghcr.io/vegardengen/unifi-network-operator:latest

For Contributors

Run checks locally before pushing:

# Format code
make fmt

# Run linters
make vet

# Run tests
make test

# Lint Helm chart
make helm-lint

# Test Docker build
docker build -t test .

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         GitHub Repository                        │
│                  vegardengen/unifi-network-operator              │
└─────────────────────────────────────────────────────────────────┘
                                 │
                ┌────────────────┼────────────────┐
                │                │                │
                ▼                ▼                ▼
        ┌──────────────┐ ┌──────────────┐ ┌─────────────┐
        │ Pull Request │ │ Push to Main │ │  Tag Push   │
        │  Validation  │ │              │ │   (v*.*)    │
        └──────────────┘ └──────────────┘ └─────────────┘
                │                │                │
                ▼                ▼                ▼
        ┌──────────────┐ ┌──────────────┐ ┌─────────────┐
        │   • Go Fmt   │ │ Docker Build │ │   Release   │
        │   • Go Vet   │ │   & Push     │ │  Workflow   │
        │   • Tests    │ │              │ │             │
        │   • Helm     │ │ Helm Chart   │ │  • Docker   │
        │     Lint     │ │   Release    │ │  • Helm     │
        │   • Docker   │ │              │ │  • GitHub   │
        │     Build    │ │              │ │    Release  │
        └──────────────┘ └──────────────┘ └─────────────┘
                                 │                │
                                 ▼                ▼
                         ┌───────────────────────────┐
                         │  GitHub Container Registry │
                         │  ghcr.io/vegardengen/...  │
                         └───────────────────────────┘
                                 │
                                 ▼
                         ┌───────────────────────────┐
                         │    GitHub Pages (Helm)    │
                         │  vegardengen.github.io/   │
                         └───────────────────────────┘

Workflows

1. PR Validation (pr-validation.yaml)

Triggers: Pull requests to main

Steps:

1. Code formatting check (go fmt)
2. Static analysis (go vet)
3. Unit tests with race detection
4. Coverage upload to Codecov
5. Helm chart linting
6. Template rendering validation
7. Test Docker build

Purpose: Ensure code quality before merging

2. Docker Build & Push (docker-build-push.yaml)

Triggers:

• Push to main or feature/** branches
• Push of tags starting with v*
• Pull requests (build only, no push)

Steps:

1. Run tests
2. Set up QEMU for cross-compilation
3. Set up Docker Buildx
4. Extract metadata for tags
5. Build for multiple architectures
6. Push to GitHub Container Registry

Image Tags Created:

• Branch builds: main, feature-xyz
• Version tags: v1.0.0, 1.0.0, 1.0, 1
• Latest: latest (from main branch)
• Commit SHA: main-abc1234

3. Helm Chart Release (helm-release.yaml)

Triggers:

• Push to main with changes in helm/ directory
• Manual workflow dispatch

Steps:

1. Package Helm chart
2. Create GitHub release for chart
3. Update Helm repository index
4. Publish to GitHub Pages

Output: Helm repository at https://vegardengen.github.io/unifi-network-operator

4. Complete Release (release.yaml)

Triggers:

• Push of version tags (e.g., v1.0.0)
• Manual workflow dispatch with version input

Steps:

1. Build Phase:

   • Run tests
   • Build multi-arch Docker images
   • Push with version tags and latest

2. Chart Phase:

   • Update Chart.yaml with version
   • Update values.yaml with image tag
   • Package Helm chart
   • Release chart to repository

3. Release Phase:

   • Generate release notes
   • Create GitHub release
   • Attach Helm chart package
   • Mark as pre-release if needed

Pre-release Detection: Tags containing alpha, beta, or rc are marked as pre-releases

Release Process

Creating a New Release

1. Prepare the release:

   # Ensure you're on main and up to date
   git checkout main
   git pull github main
   
   # Update CHANGELOG.md with release notes
   # Commit any final changes
   

2. Create and push the tag:

   # Create an annotated tag
   git tag -a v1.0.0 -m "Release v1.0.0: Description of changes"
   
   # Push the tag
   git push github v1.0.0
   

3. Monitor the release:

   • Go to Actions tab on GitHub
   • Watch the "Release" workflow
   • Check for any errors

4. Verify the release:

   # Check Docker image
   docker pull ghcr.io/vegardengen/unifi-network-operator:v1.0.0
   
   # Check Helm chart
   helm repo update
   helm search repo unifi-network-operator
   
   # Check GitHub release page
   # https://github.com/vegardengen/unifi-network-operator/releases
   

Version Numbering

Follow Semantic Versioning:

• MAJOR (X.0.0): Breaking changes
• MINOR (0.X.0): New features, backward compatible
• PATCH (0.0.X): Bug fixes, backward compatible

Pre-release tags:

• v1.0.0-alpha.1 - Early preview
• v1.0.0-beta.1 - Feature complete, testing
• v1.0.0-rc.1 - Release candidate

Artifact Locations

Docker Images

Repository: ghcr.io/vegardengen/unifi-network-operator

Access:

# Pull latest
docker pull ghcr.io/vegardengen/unifi-network-operator:latest

# Pull specific version
docker pull ghcr.io/vegardengen/unifi-network-operator:v1.0.0

Platforms: linux/amd64, linux/arm64

Helm Charts

Repository: https://vegardengen.github.io/unifi-network-operator

Access:

# Add repository
helm repo add unifi-network-operator https://vegardengen.github.io/unifi-network-operator

# Search charts
helm search repo unifi-network-operator

# Install
helm install my-release unifi-network-operator/unifi-network-operator

Also available: As attachments on GitHub Releases

Configuration

Repository Settings Required

1. Actions Permissions:

   • Settings → Actions → General
   • Workflow permissions: Read and write
   • Allow GitHub Actions to create releases: ✓

2. GitHub Pages:

   • Settings → Pages
   • Source: Deploy from branch
   • Branch: gh-pages / / (root)

3. Package Visibility (After First Push):

   • Profile → Packages → unifi-network-operator
   • Package settings → Change visibility → Public

Branch Protection (Recommended)

• Settings → Branches → Add rule for main
• Require pull request reviews
• Require status checks: lint-and-test, helm-lint, docker-build
• Require branches to be up to date

Troubleshooting

Common Issues

"Resource not accessible by integration"

• Fix: Enable read/write permissions in repository settings

Docker push fails

• Check package visibility settings
• Verify GITHUB_TOKEN permissions

Helm chart not updating

• Ensure gh-pages branch exists
• Check GitHub Pages is enabled
• Wait 5-10 minutes for CDN propagation

Release workflow fails

• Check Chart.yaml version is unique
• Verify all templates are valid YAML
• Review workflow logs for specific error

Debug Locally

# Test Helm rendering
make helm-template

# Lint Helm chart
make helm-lint

# Build Docker image
docker build -t test:latest .

# Run tests
make test

# Check formatting
make fmt
make vet

Monitoring

Workflow Status

Check at: https://github.com/vegardengen/unifi-network-operator/actions

Artifacts

• Docker Images: https://github.com/vegardengen/unifi-network-operator/pkgs/container/unifi-network-operator
• Releases: https://github.com/vegardengen/unifi-network-operator/releases
• Helm Repository: https://vegardengen.github.io/unifi-network-operator

Metrics

• Build success rate
• Test coverage (via Codecov)
• Release frequency
• Download statistics (via GitHub Insights)

Security

Container Scanning

Consider adding:

• Trivy vulnerability scanning
• Dependabot alerts
• SBOM generation

Secrets Management

• Use GitHub Secrets for sensitive data
• Never commit credentials
• Rotate tokens regularly

Supply Chain Security

• Images built from source
• Signed releases (future enhancement)
• SBOM attached to releases (future enhancement)

Future Enhancements

• Automated vulnerability scanning
• Signed container images (cosign)
• SBOM generation
• Automated changelog generation
• Release drafter for draft releases
• Automated version bumping
• Integration tests in CI
• Performance benchmarking
• Automated security scanning

References

• GitHub Actions Documentation
• Helm Chart Best Practices
• Container Best Practices
• Semantic Versioning

Support

For CI/CD issues:

1. Check workflow logs in Actions tab
2. Review .github/README.md for detailed docs
3. See .github/SETUP.md for setup instructions
4. Open an issue with workflow logs attached