Skip to content
FluxGate

Enterprise · Code references

Set up with GitLab CI

One reviewed job and three CI/CD variables make every push to the default branch update the flag's code references.

Builds on:Code references

Video coming soon

Set up with GitLab CI

Before you start

  • A system client token with the scopes Code references write and Evaluate (Overview).
  • The Maintainer role on the GitLab project, to add CI/CD variables.

Add the job

  1. Add the job to .gitlab-ci.yml. The job receives FLUXGATE_TOKEN, so run only a copy you reviewed:

    • Copy the job (recommended). Download fluxgate-code-refs.gitlab-ci.yml, review it and paste it into .gitlab-ci.yml. The job then changes only when you change it.

    • Include it with a checksum. With integrity (GitLab 17.9 or later), GitLab runs the remote file only when its SHA-256 matches. Download and review the file, then print the value from that copy:

      bash
      openssl dgst -sha256 -binary fluxgate-code-refs.gitlab-ci.yml | openssl base64 -A
      yaml
      include:
  - remote: https://flux.forgeopslabs.com/downloads/code-refs/fluxgate-code-refs.gitlab-ci.yml
    integrity: sha256-<the value printed above>

      When the template changes, the pipeline fails until you review the new file and update integrity. Do not include the file without integrity: a changed file would run with your token.

  2. In GitLab, open Settings, CI/CD, Variables. Add FLUXGATE_URL (your API URL, such as https://flags.example.com/api/v1), FLUXGATE_TOKEN (the system client token, masked) and FLUXGATE_VERSION (the FluxGate release, such as v2.0.1; the job downloads its CLI from https://flux.forgeopslabs.com/downloads/releases/<version>/).

  3. Push to the default branch. The job fluxgate-code-refs runs.

The job runs on debian:bookworm-slim, because the CLI build needs glibc. It runs only on the default branch ($CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH), downloads the CLI archive, checks it against SHA256SUMS, and scans. The scanner reads the project path, branch, commit and default branch from GitLab's CI variables.

Deleted branches and more branches

GitLab runs no pipeline when a branch is deleted. A daily job on the backend deletes branch scans that got no upload for 30 days. To delete one at once, run this with a token that has Code references write:

bash
fluxgate code-refs prune --repo gitlab.com/acme/shop --branch old-branch

The job scans the default branch only. To scan a release branch too, extend its rules:

yaml
rules:
  - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH == "release"

Removal issues

A pipeline schedule can run the job fluxgate-cleanup-issues, which opens one issue per flag whose code should be removed. See Open removal issues.

Optional variables

VariableMeaning
FLUXGATE_DOWNLOAD_BASEDownload the CLI and SHA256SUMS from here instead of https://flux.forgeopslabs.com/downloads/releases/<version>, for example a mirror inside your network
FLUXGATE_CONTEXT_LINESLines sent above and below each match, 0 to 5. Default 1. Use 0 to send no code
FLUXGATE_SCAN_ARGSExtra scan arguments, separated by spaces and written without quotes, for example --exclude generated/**

For a self-managed GitLab, the scanner builds the repository name from CI_SERVER_HOST and CI_PROJECT_PATH. Lines on the feature page link to files only for github.com and gitlab.com; for other hosts add --browse-url to FLUXGATE_SCAN_ARGS, for example --browse-url https://git.example.com/acme/shop/src/{commit}/{path}. The template must contain {path} and may contain {commit}, {branch} and {line}.