ci-conventions

Files (1)

• SKILL.md

SKILL.md (first lines)

# CI conventions

What a pipeline does and why, whatever runs it. The *how* for a given
platform is in `github-actions-conventions` or `gitlab-ci-conventions`.

## The canonical pipeline set

Create exactly these, conditioned on what the repo contains. The platform
skill says how each one maps onto files and triggers.

- **`quality`**: always. It runs `pre-commit run --all-files` **and** the test
  suite, on every change proposal (PR/MR) and on every push to the default
  branch. The `language: system` hooks shell out to real binaries, so the job
  installs **every** tool the hooks need (toolchain + `helm`, `helm-docs`,
  `hadolint`, `trivy`, …) before running `pre-commit`. This is the single
  quality gate. Don't scatter fmt/lint/test across ad-hoc pipelines.
- **`build`**: when a `Dockerfile` exists. It builds the image, scans it, and
  **pushes only when asked**, meaning a manual run with a `push` input or the
  `release` pipeline. A plain push or change proposal builds and scans
  without pushing (validation only). Tags and labels come from the
  platform's metadata (a metadata action, predefined variables). Never
  hand-roll tag strings in several places.
- **`security`**: only when the repo holds something `pre-commit` does not
  scan: a dependency lockfile, or an image it publishes. It runs the
  Trivy vulnerability scans (below) on every change proposal, on push to the
  default branch, **daily on a schedule**, and on manual trigger. A repo of
  docs, configuration or skills has no `security` pipeline.
- **`chart`**: when a Helm chart exists. It publishes the chart as an **OCI
  artefact**. The chart has its **own release lifecycle**, decoupled from the
  app. It triggers on the `chart-X.Y.Z` tag namespace, pre-release
  `chart-X.Y.Z-rcN` tags included (plus manual runs), and never on a change
  proposal, where `helm lint` inside `pre-commit` is the validation. The chart
  version comes from the tag (`helm package --version <v>`). `appVersion`
  stays whatever `Chart.yaml` pins. It runs the same drift guard as `release`
  on every chart tag: `Chart.yaml` always, the README's `helm install
  --version` on a stable tag. A chart tag never gets a release page. The only
  release pages are the app's.
- **`release`**: when the repository publishes an application artefact (an
  image, a package, a binary); a chart alone is the `chart` pipeline's. It is
  the app-release orchestrator, triggered by a `vX.Y.Z` tag. It derives the
  version from the tag, **refuses to run when the committed version
  disagrees** (the drift guard in `release-script-conventions`), runs `build`
  with push enabled, then creates the platform's release page with generated
  notes. It does **not** publish the chart. When a documentation site exists,
  it also redeploys it once the release page is created. A repo of docs,
  configuration or skills has no `release` pipeline.
- **`docs`**: when the repo has a documentation site. It builds the site on
  every change proposal that touches it, and deploys it from the default
  branch only: on a push there, and on a stable release. What it builds, and
  why a release redeploys from the default branch rather than the tag, is in
  `starlight-conventions`.

### Pre-release tags

**A pre-release tag (`vX.Y.Z-rcN`, any tag with a `-`) publishes the image and
stops there: no release page.** An rc exists to be tested. A release page for
it would carry the full generated changelog, and the final release would then
repeat it (or, diffed against the rc, show almost nothing).

For a stable release, the notes start from the **previous stable tag** (the
greatest `vX.Y.Z` without a hyphen below the current one, `sort -V`), never
from an rc. With no previous stable tag, let the platform pick.

## Trivy: misconfigurations in pre-commit, vulnerabilities in `security`

**`trivy config` is a `pre-commit` hook**, so it gates every commit and, through
`quality`, every pipeline. It covers the misconfiguration checks: `DS-` for a
`Dockerfile`, `KSV-` for a rendered chart, provider-prefixed IDs (`AWS-0086`,
`GCP-0001`, …) for Terraform. The hooks are in `docker-conventions`,
`helm-conventions` and `terraform-conventions`. A misconfiguration is
deterministic, so it belongs at commit time, and it fails on **every**
finding, whatever its severity.

The *vulnerability* side lives in the `security` pipeline, because it needs a
database that changes every day and a network to fetch it. A CVE appears
against code nobody touched. **A repo that only scans on change proposals is
scanning the day it merged, not today.**

What to run:

- **`trivy image`** on the image `build` just produced, **in the same job,
  before anything is pushed**, change proposals included. Build into the
  local store or a tarball, scan, then push that same image. Publishing a
  known-vulnerable image and scanning it afterwards is the wrong order, and a
  "staging" tag in a registry is still a published image.
- **`trivy fs`** on the checkout, for the lockfiles (`Cargo.lock`, `uv.lock`,
  `package-lock.json`) and secrets. This is what catches a vulnerable
  transitive dependency the manifest never mentions.

How to run the vulnerability scans:

- **Fail on `HIGH` and `CRITICAL`**, and use `ignore-unfixed` on that
  blocking gate only. This applies to CVEs alone: a misconfiguration has no
  upstream fix to wait for. A CVE with no upstream fix can't be actioned by the
  contributor in front of it. Blocking on it teaches everyone that red is
  normal, which is how a real finding gets waved through.
- **Report everything else where people look**: the platform's code-scanning
  or vulnerability report, via a second, non-failing scan whose upload runs
  even when the gate failed. A finding that only exists in a job log is lost.
- **Pin the Trivy version** (action SHA, image tag) like any other tool, and
  use the report templates shipped with that version. Never fetch a template
  from a branch URL at run time.
- **Cache the vulnerability DB.** It is a large artefact pulled from a
  registry on every run, and the failure mode is a rate-limited registry
  taking the whole pipeline down. Behind a registry proxy, point
  `--db-repository` / `--java-db-repository` at the mirror.

### The scheduled re-scan

- **Daily**, at an **off-hour minute** (never `0`). Top-of-the-hour runs are
  the first to be delayed or dropped under load.
- **Scan what is published, not a rebuild.** A scheduled run has no fresh
  build, and rebuilding `main` would pull patched base layers and report a
  clean image nobody runs. It scans the image of the **latest stable
  release**, pulled by its tag. `trivy fs` runs on the default branch as
  usual. A repo with no image runs `trivy fs` alone.
- **Keep the gate.** Nobody waits on a cron, so a red scheduled run *is* the
  notification that a new `HIGH`/`CRITICAL` CVE exists.

From leroyguillaume/claude, MIT.

More from leroyguillaume/claude