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.
When the pipeline fails
Section titled “When the pipeline fails”- Read the log first.
/ci-debug <pipeline or MR>fetches the failed logs, finds the root cause, and prescribes a fix without changing anything. - 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 withmain. - 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.
What runs out of the box
Section titled “What runs out of the box”| 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 |
What each governance job is for
Section titled “What each governance job is for”| 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 |
Go deeper
Section titled “Go deeper”Dependency and secret scanning
Section titled “Dependency and secret scanning”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.
Stack templates
Section titled “Stack templates”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.
Smoke-testing a built web image
Section titled “Smoke-testing a built web image”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.ymlon 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 hostsome-job:image: $DOCKER_HUB_MIRROR/library/alpine:3.23DOCKER_HUB_MIRRORis a naming suggestion, not a variable the template already uses. Give it a default: unset, the reference becomes/library/alpine, which is invalid. Note thatscripts/check-ci-image-pins.pyaccepts a reference that holds a CI variable only in one form: the whole reference is the variable ($NAMEor${NAME}), a top-levelvariables:entry for that name in the CI files is pinned by digest, no job sets the name in its ownvariables:block, and the value names a trusted repository (stock alpine or this project’sci-baseimage; 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).
Making the pipeline fast
Section titled “Making the pipeline fast”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-templaterewritesCI_BASE_IMAGEin.gitlab-ci.ymlto stockalpine:3.23, pinned by the digest theshell-portabilityjob 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 ownci-basepath and is red onscripts/check-ci-image-pins.pyuntil it is reset. -
Prebuilt (opt-in):
ci/ci-base-image.ymlbuildsci/images/ci-base/Dockerfilewith 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 variableCI_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:- Pin. After the first build and sign succeed on the default branch, copy the
name:tag@sha256:<digest>the build job prints intoCI_BASE_IMAGEin 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. - Schedule. In Build > Pipeline schedules, create a weekly schedule on the
default branch with the variable
CI_BASE_IMAGE_REBUILDset totrue, 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-baseimage in 0.8 (macrodream/blueprint#308). The weekly schedule is created by hand after that change merges, and is not part of the repository. - Pin. After the first build and sign succeed on the default branch, copy the
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:
alpineordocker.io/library/alpine, the default. - This project’s
ci-baseimage: either the literal text$CI_REGISTRY_IMAGE/ci-base:<tag>@sha256:<digest>, or the expanded path the build job prints, such asregistry.gitlab.com/<group>/<project>/ci-base:latest@sha256:<digest>. The expanded path must equal theCI_REGISTRY_IMAGEGitLab predefines in the job running the gate, plus aci-basepath segment. In a merge request pipeline the anchor is the MR’s target project instead (CI_REGISTRYplus the lowercasedCI_MERGE_REQUEST_PROJECT_PATH). A fork MR’s pipeline runs in the fork, whereCI_REGISTRY_IMAGEis the fork’s path, so on GitLab’s predefined values the fork’s ownci-basefails 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 aci-basesegment, such asevil.example/ci-baseor 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:
python3 scripts/ci-speed-audit.py --pipelines 5 # default branchpython3 scripts/ci-speed-audit.py --pipeline <id> # one MR pipelineThe 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.
Running the checks yourself
Section titled “Running the checks yourself”make pre-push-checks # what the pre-push hook runs: collision, parity, and the gate suitemake gate-self-tests # prove every check script can still failmake help # list every target