Skip to content

CI pipeline

The big picture: GitLab runs a pipeline on every MR, on main, on a production branch if you use one, and on tags. Out of the box it runs governance jobs that check the process itself. You switch on stack jobs (lint, test, license) for your language.

Why it matters: CI is the one reviewer that never skips a step. A required green pipeline means “this passed the same checks every other change passed,” not “the author says it’s fine.”

How it works:

  • Governance jobs need no setup: changelog present, no stale markers, every check script still able to fail, secret and dependency scans.
  • Stack jobs come from ci/*.yml. Uncomment the line for your stack in .gitlab-ci.yml.
  • Almost everything CI checks, you can check before pushing, with make pre-push-checks. The Git pre-push hook runs it for you.
  1. Read the log first. /ci-debug <pipeline or MR> fetches the failed logs, finds the root cause, and prescribes a fix without changing anything.
  2. Then fix it. /fix-mr <MR> fixes, commits, pushes, and re-checks — up to three rounds, running the cheapest check that fits the fix. It also resolves conflicts with main.
  3. Never just retry without a code change, unless the failure is clearly infrastructure (a runner died, a registry timed out). Running your own runners? See Private CI runners.

Why: a retry that “fixes” a failure hides a flaky test or a real bug until it bites harder.

Stage Jobs
lint changelog-check, mr-followups, mr-gate-ledger, stale-references, cc-claims, gate-selftest-parity, prepush-parity, spec-check, spec-trace, tooling-self-tests, sigpipe-readers, shell-portability, shellcheck, nul-bytes, ci-yaml-lint, single-fastpath-table, skill-names, load-bearing, edition-boundary, version-lockstep, artifact-assertions, onboarding-customize-e2e, reset-tree-self-tests, release-pipeline-ci-file; on tags, release-pipeline-gate
test app-fixture-gates, docs-internal-links (from ci/docs.yml), website:build; with a container registry, ci-base-image:verify on an MR that changes the base image (from ci/ci-base-image.yml)
security GitLab SAST and secret-detection components, osv-scan, gitleaks-scan
deploy pages (publishes the docs site); with a container registry, ci-base-image:build and ci-base-image:sign (from ci/ci-base-image.yml, on the default branch when the base image changes or on an opted-in schedule); deploy-staging / deploy-production templates, commented out
Job Catches Why it’s worth a job
changelog-check (MRs) A product change with no changelog.d/ fragment Release notes can’t be reconstructed later
mr-gate-ledger (MRs) A gate: line in the MR’s ## Gates section whose outcome is free text, not <N> findings, n/a or skipped; and an MR whose diff touches the rigor floor without the rigor: level its tier sets (strict or strict-light) and that level’s gate lines gate-yield.py silently drops a line it cannot parse, so the gate’s yield is lost; and a risky path audited at the cheap tier is how a release blocker slips through
mr-followups (MRs) A ## Follow-ups bullet or DEFERRED Requirements cell in the MR description that names no open issue “We’ll do it later” with no issue means never
cc-claims (MRs, main, schedules) A Claude Code behavior claim without a code.claude.com link and checked: YYYY-MM-DD A statement about the harness decays silently; stale dates warn on schedules only
stale-references (MRs, main, schedules) STUB/WIP markers and the other stale-reference rules (renamed skills, agents or unknown names used as slash commands, missing ADR links, TODO(#N) at a closed issue); the list is in Harness gates A TODO whose issue closed is a promise nobody is tracking
gate-selftest-parity A check script with no --self-test, or one that self-tests in a different job A check that can’t prove it still fails might be silently broken
prepush-parity A CI check you can’t also run before pushing Finding out in CI costs a pipeline; finding out locally costs seconds
tooling-self-tests Broken release, worktree, and setup tooling These scripts run rarely, so they break silently
sigpipe-readers, shell-portability, shellcheck, nul-bytes Shell-script bugs that make a check report the wrong answer A check that lies is worse than no check
ci-yaml-lint A repeated key or unknown keyword in a CI file, including the add-ins this repo never includes YAML keeps the last duplicate silently, so a whole variables block can vanish
load-bearing Deletion of a one-line call that wires in a guard Deleting it leaves every test green and the guard off
edition-boundary The open-source tree naming a package listed in edition-boundary.conf (a no-op until that file exists) An enterprise import in the public core couples it to private code, and nothing else goes red
version-lockstep A file holding the version that disagrees with the others Ships a release stamped with the wrong version
artifact-assertions A tag-time publish job that would upload nothing Tag-time jobs never run on MRs, so they fail at the worst moment
onboarding-customize-e2e (when setup files change) make customize / make doctor breaking for a fresh clone, or a make <target> the quickstart names failing on an unconfigured tree The first experience of a new project shouldn’t be a crash
reset-tree-self-tests (same triggers) A tooling-self-tests command that passes in this repo but fails in the tree the default reset leaves, for example one that reads website/ An adopter’s first pipeline shouldn’t fail on a Blueprint test for a directory the reset removed
release-pipeline-gate (tags) Publishing a tag from a commit where any job in its own branch pipeline failed, allow_failure jobs included (job-by-job judgment ships in 0.8) Stops a broken commit from becoming a release
release-pipeline-ci-file (ships in 0.8) A tag-triggered publish job that does not strictly needs: release-pipeline-gate Keeps every publish job behind the gate
app-fixture-gates The app-aware checks (schema-to-types parity, real-time event reachability, migration numbering, coverage of added files, plus the edition-boundary scan) failing on a realistic app Blueprint’s own tree has no app, so these are proven against a generated fixture instead
spec-check (when docs/specs/ or the gate changes, and on main) A spec missing a required section, or the gate’s own parser broken A spec that fails the gate is an import that creates wrong issues
spec-trace (main and schedules; the self-test alone when the gate, its reader, the spec parser or .gitlab-ci.yml changes) An imported spec whose Issue: #N is gone from the tracker, or whose issue’s Spec: line names another feature; fails closed when the tracker is unreachable The links /spec import writes rot silently once issues are closed, moved or renumbered

The GitLab SAST and secret-detection components report; on their own they don’t fail the pipeline. Two jobs close that gap:

Job What it does Configure with
osv-scan Scans every lockfile in the tree against the OSV.dev advisory database. Fails at or above OSV_SEVERITY_THRESHOLD (default HIGH); a finding below it is a non-blocking warning. The OSV_SEVERITY_THRESHOLD CI/CD variable (LOW, MEDIUM, HIGH, CRITICAL). Accept a risk with a documented, expiring IgnoredVulns entry in an osv-scanner.toml next to the lockfile.
gitleaks-scan Scans the whole working tree for secrets — not just the diff. The same tool runs as a pre-commit hook (installed by make setup), so a secret is stopped before it’s even committed. .gitleaks.toml at the repo root; add a documented allowlist entry for a genuine false positive.

Fail closed: if the advisory scan can’t complete (network down, database unreachable), osv-scan fails instead of quietly passing. The only override is ALLOW_UNRESOLVED=1, for a runner that genuinely can’t reach the internet — set it as an explicit, reviewable CI/CD variable.

Uncomment the include in .gitlab-ci.yml. Each file has its settings (source folder, coverage threshold, image version) at the top.

File For Jobs
ci/python.yml Python python-lint (ruff), python-test (pytest + coverage), python-license-check, migration-numbering, ws-event-reachability, serializer-ts-parity, and two opt-in jobs below
ci/node.yml Node.js node-lint (eslint), node-test (vitest + coverage), node-license-check, added-files-covered
ci/go.yml Go go-lint (golangci-lint), go-test, go-vuln-check (govulncheck)
ci/docker.yml Docker docker-build (kaniko, no privileged mode), compose-project-names
ci/helm.yml Helm charts helm-registry-drift, helm-install, helm-upgrade — see Deployment options
ci/docs.yml A docs site docs-internal-links — included by default; it does nothing until a docs site exists
ci/sonar-exclusions.yml Sonar ignore criteria sonar-exclusions — off by default; fails when an ignore-criterion ruleKey does not exist or is inactive, exits 2 (fails closed) when the Sonar API cannot be reached or understood unless ALLOW_UNRESOLVED=1, and exits 1 on a dead key or a rejected token (401/403) (see External validation)
ci/trivyignore-expiry.yml Container scanner suppressions trivyignore-expiry — off by default; fails on a .trivyignore entry with no exp:YYYY-MM-DD, an expired one, or one dated more than TRIVYIGNORE_MAX_DAYS (default 180) out. It does not run Trivy, and does nothing without a .trivyignore (see External validation)
ci/sonar-complexity.yml Python scripts cognitive-complexity — off by default; read its header first, because it false-positives on legitimately branchy code (a local approximation; for a real Sonar scan see External validation)
ci/mutation.yml Python (mutmut example) mutation-selftest, then nightly mutation-shard and mutation-report — off by default, schedule-only; see Testing AI-written code
ci/cloudflare-deploy.yml A separate marketing-site repo Preview, staging and manual production deploy jobs for Cloudflare — an opt-in template, fully commented out; copy it to that repo, see Marketing site on Cloudflare

Python: schema fuzzing and a nightly load test

Section titled “Python: schema fuzzing and a nightly load test”

ci/python.yml ships two jobs that need a running API, not just source files. Each stays out of the pipeline entirely until you provide the startup script it names.

Job What it does Turn it on with
python-schema-fuzz Uses schemathesis to hit your live API with generated input and fails when a real response doesn’t match your OpenAPI schema. Blocking on relevant MRs. Record accepted, triaged findings in schemathesis-baseline.json. SCHEMA_FUZZ_API_BOOT_SCRIPT — your script that migrates, seeds a small fixture, starts the API, and waits until it’s serving
python-nightly-load-test Measures p50/p95/p99 latency for chosen read endpoints and fails when one exceeds its p95 budget. Scheduled, not per-MR. LOAD_TEST_API_BOOT_SCRIPT (seeds a large fixture) plus at least one target in nightly-load-test-budgets.json

Why they matter: the fuzzer is the one check that asks whether your schema describes what the server actually returns — not whether the schema agrees with itself. The load test catches a slowdown that keeps the query count the same (a missing index, data growth), which no code review can see.

For why fuzzing matters when an AI writes the tests, and what mutation testing adds, see Testing AI-written code.

Yes, but: the load test’s default budget (500 ms) is a placeholder, not a measurement. Derive real budgets with python3 scripts/nightly_load_test.py --measure-only.

If your project ships a single-page-app container, boot the built image in CI and prove it serves its own JS and CSS before you push it. Blueprint ships an optional template for this; see Served-assets smoke test.

Optional: dependency updates and a Docker Hub mirror

Section titled “Optional: dependency updates and a Docker Hub mirror”

Two things are options, not defaults:

  • Renovate opens MRs for dependency updates. It needs the hosted Renovate app or a self-hosted Renovate runner; the config file alone does nothing. Keep renovate.json (or .github/dependabot.yml on GitHub) and delete the other; only one should run. The MRs go through the same pipeline and gates as any other change.

  • A Docker Hub pull-through mirror. Anonymous Docker Hub pulls are rate limited per runner IP, so a busy shared runner can fail a build on a pull, not on your code. The simplest fix is on the runner: configure its Docker daemon with registry-mirrors, or use GitLab’s Dependency Proxy. Running your own runners also gets you off a shared IP; see Private CI runners. To do it per project instead, define a variable that defaults to Docker Hub and override it where a mirror exists:

    variables:
    DOCKER_HUB_MIRROR: "docker.io" # override with your mirror's host
    some-job:
    image: $DOCKER_HUB_MIRROR/library/alpine:3.23

    DOCKER_HUB_MIRROR is a naming suggestion, not a variable the template already uses. Give it a default: unset, the reference becomes /library/alpine, which is invalid. Note that scripts/check-ci-image-pins.py accepts a reference that holds a CI variable only in one form: the whole reference is the variable ($NAME or ${NAME}), a top-level variables: entry for that name in the CI files is pinned by digest, no job sets the name in its own variables: block, and the value names a trusted repository (stock alpine or this project’s ci-base image; see Making the pipeline fast). Anything else, such as $DOCKER_HUB_MIRROR/library/alpine:3.23, fails unless it is allowlisted by its exact text. A “toomanyrequests” failure is infrastructure, so retrying the job is correct (see When the pipeline fails).

Most of a governance job’s time is its own script. What is left is setup: pulling the image, cloning, installing packages, and waiting for jobs it does not depend on. Measured on three Blueprint MR pipelines in October 2026, before the changes below: pre-script time (image pull, executor prepare, clone) was about 1.5 s per job, the clone itself about 0.8 s, and runtime package installs 2 to 16 s per job. The biggest single cost was waiting: website:build and docs-internal-links started about 600 s into the pipeline, behind the two longest lint jobs, although neither uses anything those jobs produce.

Start each job when its inputs are ready (needs:). A job with no needs: waits for every job in every earlier stage. needs: [] starts it at once; a list starts it when those jobs finish, whatever stage they are in. Keep stages: for reading order and for deploy jobs, which should wait for everything. Blueprint gives needs: [] to the test- and security-stage jobs that read only the checkout, so the security scanners run alongside lint and test in MR, default-branch and branch pipelines. That includes the SAST and secret-detection component jobs: a job in .gitlab-ci.yml with the same name as an included job merges its keys into it, so .gitlab-ci.yml adds needs: [] to .sast-analyzer (the template every SAST analyzer job extends), semgrep-sast and secret_detection. The severity gates in ci/scanner-gates.yml still needs: their scanner’s report, with optional: true so a pipeline without the scanner job still gets created and the gate fails closed on the missing report. pages and ci-base-image:build (below) have no needs:, so they run only once every earlier stage has passed. From 0.8, image-sign-attest has needs: [release-pipeline-gate], so add your image build job to that list in ci/image-signing.yml; pages takes website:build’s output through dependencies:, which picks artifacts without changing when the job starts. A job that should wait on purpose, such as an expensive cluster drill you do not want to run while lint is red, carries a # ci-speed-audit: stage-wait — <reason> comment. See GitLab’s needs reference and pipeline efficiency.

Bake the toolchain into a base image. The governance jobs run on $CI_BASE_IMAGE and install their packages with sh scripts/ci-apk-ensure.sh PKG..., which installs only the packages the image does not already have. Two modes:

  • Default for your project, no registry needed: customize.sh --reset-template rewrites CI_BASE_IMAGE in .gitlab-ci.yml to stock alpine:3.23, pinned by the digest the shell-portability job uses. Every job installs its packages at runtime, as before, so a project with no container registry stays green. This is also the fallback if you never build the image. A clone not yet reset ships Blueprint’s own ci-base path and is red on scripts/check-ci-image-pins.py until it is reset.

  • Prebuilt (opt-in): ci/ci-base-image.yml builds ci/images/ci-base/Dockerfile with kaniko, pushes it to $CI_REGISTRY_IMAGE/ci-base, and signs it with the same cosign and SBOM flow as release images (scripts/attest-image-sbom.sh). It runs on the default branch when the Dockerfile changes, and on a pipeline schedule you create with the variable CI_BASE_IMAGE_REBUILD=true, so Alpine security patches land without anyone remembering. Every job there is gated on $CI_REGISTRY, so it does nothing without a registry. Switching over takes two steps, in this order:

    1. Pin. After the first build and sign succeed on the default branch, copy the name:tag@sha256:<digest> the build job prints into CI_BASE_IMAGE in an MR. When Renovate runs, it can open an MR for each new digest (renovate.json, customManagers), but Blueprint’s own project does not run it today (macrodream/blueprint#308), so there the digest is copied by hand. Until an MR moves the pin, a rebuild publishes a digest no job uses, and no job runs a new image without review.
    2. Schedule. In Build > Pipeline schedules, create a weekly schedule on the default branch with the variable CI_BASE_IMAGE_REBUILD set to true, and run it once to confirm it publishes a new digest. A schedule is a project setting, not a file, so no MR can create it.

    Blueprint’s own pipeline ships pinned to its ci-base image in 0.8 (macrodream/blueprint#308). The weekly schedule is created by hand after that change merges, and is not part of the repository.

Keep one job on stock alpine. The ci-base image installs gawk and coreutils, which the gate-selftest-parity, mr-followups, cc-claims and skill-names jobs need, so once CI_BASE_IMAGE points at it awk and stat in every job that uses it are the GNU versions (sh stays BusyBox ash). A reset project has the BusyBox ones. Blueprint therefore runs the shell-portability job on stock alpine:3.23, pinned by digest, so its static lint and the awk inside check-shell-portability.sh run on BusyBox. That job does not run other scripts on BusyBox; a real run on it is tracked in macrodream/blueprint#363. Keep the two digests (that job’s and the Dockerfile’s FROM) in step; when Renovate runs, it bumps each separately.

Keep the pin in .gitlab-ci.yml. A project-level CI/CD variable with the same name outranks the file at run time (variable precedence), which hides the image from review and from scripts/check-ci-image-pins.py. That gate accepts image: $CI_BASE_IMAGE only because it checks the value the file defines, and it fails a job that overrides the variable in its own variables: block.

The gate also checks which repository that value names, because a digest pins the bytes, not who chose them: evil.example/tools@sha256:... is pinned too. It accepts exactly two repositories, from one list in the script (STOCK_BASE_REPOS and the comment above it), each still pinned by digest:

  • Stock alpine: alpine or docker.io/library/alpine, the default.
  • This project’s ci-base image: either the literal text $CI_REGISTRY_IMAGE/ci-base:<tag>@sha256:<digest>, or the expanded path the build job prints, such as registry.gitlab.com/<group>/<project>/ci-base:latest@sha256:<digest>. The expanded path must equal the CI_REGISTRY_IMAGE GitLab predefines in the job running the gate, plus a ci-base path segment. In a merge request pipeline the anchor is the MR’s target project instead (CI_REGISTRY plus the lowercased CI_MERGE_REQUEST_PROJECT_PATH). A fork MR’s pipeline runs in the fork, where CI_REGISTRY_IMAGE is the fork’s path, so on GitLab’s predefined values the fork’s own ci-base fails rather than passing review and then running in every job once merged. The fork’s owner can still override those values (see below). A repository whose path merely ends in a ci-base segment, such as evil.example/ci-base or another namespace on the same registry, fails: anyone can create one. Renovate bumps only the expanded spelling, since it cannot resolve $CI_REGISTRY_IMAGE.

The value may hold no other CI variable: one in the tag or path would expand at run time, after the check, and could change where the repository ends.

Two consequences of the anchor. A ci-base value fails if any CI file defines CI_REGISTRY_IMAGE, CI_REGISTRY, CI_MERGE_REQUEST_PROJECT_PATH or GITLAB_CI in a variables: block, at the top level or in a job, or in a parallel: matrix: entry, or in a variables: value the scanner cannot read name by name (see below), because a value in the file outranks the predefined one and the file under review would vouch for itself. The scanner reads quoted keys ("NAME":), a space before the colon (NAME :), and a header with a comment or an anchor. A block it cannot read name by name (a merge key <<: *x, an alias variables: *x, a flow mapping {...}) fails closed. So does any key, in any CI file and in block or flow style, spelled in a form the scanner cannot resolve to a name, though GitLab’s YAML loader does: an explicit key (? NAME then : value), a tag, anchor or alias on the key (!!str NAME:, &a NAME:, *a :), or an escape in a double-quoted key ("imag\x65": loads as image). A job written as a flow mapping fails if it names image: (job: {image: x}), and so does any flow value after a key the scanner cannot read, which includes a job name with a space, a leading digit or a leading dot (build job: {...}, "my job": {...}, .hidden: {...}). The body of a block scalar (- |) is script text and is not read as keys. A quoted string that opens at a token start and does not close on its line fails the gate, since the scanner cannot read its later lines and one shaped like key: | would hide the keys after it. A token start is the start of the line, a position after the leading - or ? indicators, after : , or after a tag or anchor that itself sits at a token start; inside a flow collection, also after [, {, , or any :. A quote anywhere else is plain text (echo don't, echo a,'b'), as GitLab’s loader reads it. Write a multi-line script as a block scalar (- |) instead. These forms, which GitLab’s loader reads and the scanner cannot, fail closed as well (macrodream/blueprint#335): a tab anywhere outside a block scalar (image:<TAB>x, image<TAB>: x), a byte-order mark inside a file (a leading one is dropped, as GitLab drops it, so a top-level variables: behind it is read), a line opening with { or [ (a one-line flow or JSON document such as {"job": {"image": x}}, or a flow value on its own line), content after a --- marker (--- {...}), a bare - item, a block-scalar or next-line value for image:, an image or service name:, or a - component: (image: >-, name: |-), a double-quoted value holding an escape ("\x24{TAG}" loads as ${TAG}), a quoted string left open on its line (see above), a key built from a CI input ($[[ inputs.k ]]: x, which GitLab interpolates), a flow-mapping job that continues on later lines, a merge key with a flow mapping (<<: {image: x}), and an alias as the image: or services: value. A tag or anchor on a variables: or services: header (variables: !!map, services: &s) no longer hides the block, and a variables: or matrix: value that is neither a block nor a flow mapping (!reference [...], !!omap [...]) counts as setting every name. A service’s name: or an include’s component: is read whichever key of its item it is. Every key under parallel: matrix: counts as a job-level variable, so a matrix entry setting CI_BASE_IMAGE fails like a job variables: override, and so does any name in a flow mapping that holds variables: or matrix: (job: {variables: {...}}). A quote in a variables: flow mapping can hold a } or , ({A: "}", CI_BASE_IMAGE: x}), so such a mapping counts as setting every name. And a local run (make pre-push-checks, where CI_REGISTRY_IMAGE is unset) cannot know your registry path, so it passes the expanded spelling with a NOTE line and leaves the decision to the CI job; in CI with no CI_REGISTRY_IMAGE (no container registry, so no ci-base image) it fails. Export CI_REGISTRY_IMAGE to run the full check locally.

The gate is a best-effort line scanner, not a YAML parser. Three rounds of review against GitLab’s YAML loader each found spellings it read differently, and each was closed. It fails closed on every form listed on this page, but an unusual spelling the loader accepts may still pass unseen. The sound fix is to read the files with a YAML loader; that is not adopted because the CI lint images ship none, and adding one is a new dependency that needs the dependency gate and the owner’s sign-off.

What the gate does not cover: a pipeline variable, or a project or group CI/CD variable, outranks both the file and GitLab’s predefined variables at run time. That holds for every input of the check: CI_BASE_IMAGE itself, and each anchor input, CI_REGISTRY_IMAGE, CI_REGISTRY and CI_MERGE_REQUEST_PROJECT_PATH. Anyone allowed to set one can point those jobs at another image, or move the anchor the gate compares against. That includes gitleaks-history and trivyignore-expiry, two scanners whose image now comes from CI_BASE_IMAGE. No override of that kind shows up in a diff, and no gate reading the repository can see it.

The scanner reads YAML line by line, not with a YAML loader (the CI lint images ship no YAML library), so it covers the spellings listed above and fails closed on the unreadable forms a check against GitLab’s loader found; a spelling outside those lists is not proven covered. Only .gitlab-ci.yml and ci/*.yml are scanned, so an image in a file included from elsewhere is not read. It also fails some valid YAML as a false positive: a quoted string that spans lines (see above), a one-line quoted script item holding : { or : [ (- 'echo "cfg: {a}"', read as a flow value after a key the scanner cannot read; write it as - |), a tab in a trailing comment or inside a quoted value, a quote in a flow-mapping job (the scanner cannot tell whether it closes), a quote in a variables: flow mapping (variables: {A: "x"} counts as setting every name, so any whole-variable image then fails), a hidden job written as a flow mapping (.x: {...}), and an alias-like , * inside a quoted flow value (variables: {GLOB: "a, *b"}), which it reads as a key it cannot name. Write each in block style, with spaces. Skipping quoted flow values would need the scanner to track quoted strings across lines, which an earlier attempt showed opens a way to hide keys.

In a fork MR pipeline the fork’s owner sets the fork’s project variables. Setting CI_REGISTRY and CI_MERGE_REQUEST_PROJECT_PATH there moves the anchor to the fork, so the fork’s own ci-base passes, and that verdict covers a value the default branch runs after the merge, not only the fork’s pipeline. A fork MR’s green ci-yaml-lint is therefore not evidence that its CI_BASE_IMAGE is trusted: when a fork MR changes CI_BASE_IMAGE to an expanded ci-base path, the reviewer checks that the path names the target project’s registry. The fork anchor itself has not been checked against a live fork pipeline. Check Minimum role to use pipeline variables in your project’s CI/CD variable settings. Per GitLab’s CI/CD variables documentation, it defaults to no_one_allowed for new projects in new namespaces on GitLab.com (since GitLab 17.7), and to maintainer on GitLab Self-Managed and Dedicated when it is not set. The docs do not state the value for a project created before that change, so read yours rather than assume it. Nothing verifies the cosign signature before a job pulls the image: the digest pin is what jobs trust, and the signature is the audit record of which pipeline built that digest. Verifying it is tracked in macrodream/blueprint#309.

The trade-off: you now own an image. You patch it (the rebuild schedule does this, once you create it), you pay for registry storage, and the image has to exist before any job can use it. That last point is why the reset gives an adopter stock alpine. If the project, and so the registry, is private, the runner pulls the image with the job’s registry credentials; check that your runners can pull from it. Keyless signing writes the project path to Sigstore’s public transparency log; a private project should switch to key-based signing, as described in ci/image-signing.yml.

Clone only what the job needs. GIT_DEPTH: "20" is the default. That matches GitLab’s default for new projects (shallow cloning), and setting it in the file keeps it from depending on the project setting. A job that needs history (a merge base, the tag list, a full-history secret scan) sets GIT_DEPTH: "0" with a comment on that line saying why. Blueprint measured sparse checkout and did not adopt it: a whole shallow clone of this repository takes under a second, so a sparse one could save only noise. Measure your own clone time (the trace’s get_sources section) before reaching for GIT_STRATEGY, GIT_CLONE_EXTRA_FLAGS or GIT_FETCH_EXTRA_FLAGS.

Find the slow spots with /kaizen. Step 1b runs scripts/ci-speed-audit.py, which flags runtime installs, later-stage jobs with no needs:, and unexplained full clones, and ranks each finding by seconds measured from recent pipelines and job traces. A ci-apk-ensure.sh line counts as a runtime install unless its job runs on $CI_BASE_IMAGE and CI_BASE_IMAGE names a prebuilt ci-base image, so on the stock default every such line is reported. A job that stays on a stock image on purpose (it needs node or the docker CLI) carries a comment saying so; shell-portability is always reported, since it stays on stock alpine by design. Run it like this:

Terminal window
python3 scripts/ci-speed-audit.py --pipelines 5 # default branch
python3 scripts/ci-speed-audit.py --pipeline <id> # one MR pipeline

The runner-side half of the job (an S3 cache, a Docker layer cache, registry mirrors) is in Private CI runners. GitLab’s own list is Speed up job execution.

Terminal window
make pre-push-checks # what the pre-push hook runs: collision, parity, and the gate suite
make gate-self-tests # prove every check script can still fail
make help # list every target