Skip to content

CI/CD Guidelines

Pipeline Stages

Run in order; parallelize within each stage:

  1. Check — architecture check | lint & static analysis | secret scan | unit tests
  2. Build — release Docker image; build once, promote across environments
  3. Integration tests — test the image from stage 2
  4. Deploy — push to registry; manual trigger for production

Never recompile between staging and production. Inject all configuration via environment variables.

Registry Tagging

Event Tags
Pull Request pr-<N>, sha-<short> (ephemeral)
Merge to main latest, build-<N>
Git tag v1.0.0 1.0.0, stable

Makefile Targets

  • debug-build — debug symbols, no optimizations; used for development and testing.
  • release-build — no debug symbols, speed optimizations; containerized and integration-tested.

Documentation

A Git tag v1.2.3 triggers publishing the documentation (GitLab/GitHub Pages). Update GitLab/GitHub Pages on new releases only.

GitLab Hints

CI_ACCESS_TOKEN setup (required for the release job)

The release job pushes the updated CHANGELOG.md back to the default branch. This requires a token with push access and matching branch protection settings.

Required setup (once per project):

  1. Protected Branch setting — Settings → Repository → Protected Branches → main
  2. "Allowed to push": Maintainers (Developers still cannot push directly and must use Merge Requests.)
  3. Create a Project Access Token — Settings → Access Tokens
  4. Role: Maintainer
  5. Scope: write_repository
  6. Add CI/CD variable — Settings → CI/CD → Variables
  7. Name: CI_ACCESS_TOKEN
  8. Value: the token
  9. Enable Protected
  10. Protect the version tag pattern — Settings → Repository → Protected Tags
  11. Add pattern v*

Protected variables are only injected into pipelines triggered by protected branches or tags. If the tag is not protected, CI_ACCESS_TOKEN is empty and the push fails with 401.