gitlab-ci-conventions

Files (1)

• SKILL.md

SKILL.md (first lines)

# GitLab CI conventions

How the pipelines from `ci-conventions` are written on GitLab. The skill
assumes nothing about the instance. Runner tags, registry host and tier all
vary, so read them from the repo or ask. Never guess a runner tag.

## Layout and style

- One `.gitlab-ci.yml`. Once it passes a couple of hundred lines, split it
  into `.gitlab/ci/<pipeline>.yml` (`quality`, `build`, `security`, `chart`,
  `release`, `docs`, each only when `ci-conventions` calls for it), pulled
  in with `include: local:`.
- Each canonical pipeline is a **set of jobs**, not a file. Name jobs in
  lowercase kebab-case after what they do (`pre-commit`, `test`,
  `build-image`, `trivy-fs`), and keep them static. A `parallel: matrix`
  already suffixes the name.
- **`rules:` only.** Never `only:`/`except:`. They can't be combined with
  `rules:` and they hide the real trigger logic.
- `needs:` to build a DAG. Stages are for ordering the UI, not for
  sequencing jobs.
- Shared rules go through `!reference [.rules-build, rules]` rather than YAML
  anchors, because anchors don't cross `include:` boundaries. pre-commit's
  `check-yaml` rejects custom tags, so give it the `--unsafe` arg in a repo
  that uses `!reference`.
- Block style, no leading `---`, per `yaml-conventions` — with one exception:
  `!reference` takes its path in flow style, the only form GitLab documents,
  so mark the line `# yamllint disable-line rule:brackets` or the strict
  yamllint hook rejects it.

## The pipeline header

```yaml
workflow:
  auto_cancel:
    on_new_commit: interruptible
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    - if: $CI_COMMIT_BRANCH
    - if: $CI_COMMIT_TAG

default:
  interruptible: true
```

- Without the second rule, a push to a branch with an open MR runs **two
  pipelines**, a branch one and an MR one.
- `interruptible: true` on **every** job, publishing included. That is the
  GitLab form of the "cancel superseded runs" rule. Never override it to
  `false`. Auto-cancel also needs the project setting *Auto-cancel redundant
  pipelines*, which is on by default. Leave it on.

## `rules:changes` traps

- **`changes` is always true** on tag pipelines, scheduled and manual
  pipelines, and the first push of a new branch. A job filtered only by
  `changes` therefore runs on every schedule. Pair `changes` with an `if:` on
  the pipeline source:
  ```yaml
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: never
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        paths:
          - src/**/*
          - Cargo.toml
          - Cargo.lock
          - Dockerfile
          - .dockerignore
          - .gitlab/ci/build.yml
  ```
- In an MR pipeline, `changes` compares against the target branch. On a
  branch pipeline without an MR, add `compare_to: refs/heads/<default>`.
  Otherwise it compares against the previous push only.
- A job skipped by `rules` doesn't block *Pipelines must succeed*. A pipeline
  with **no** job does. Because `quality` always runs, that never happens.

## Pinning `include:`

```yaml
include:
  - component: $CI_SERVER_FQDN/<group>/<project>/<name>@<40-char-sha>  # 1.4.0
  - project: <group>/<project>
    ref: <40-char-sha>  # v1.4.0
    file: /templates/build.yml
```

- A full SHA with the version as a comment, bumped by Renovate
  (`dependency-update-conventions`). Never a branch, never a bare tag.
- No `include: remote:` from a URL you don't control. Mirror the file into a
  project and include it by SHA.
- `include: local:` is the repo itself and needs no pin.

## Publishing credentials

- **Protect the release tag patterns** (`v*`, `chart-*`) so that only
  maintainers can create them.
- Registry and API credentials for publishing are CI/CD variables that are
  **protected** and **masked** (hidden where the instance supports it).
  Protected variables only reach pipelines on protected branches and tags,
  so an MR pipeline never sees them. That is the whole point.
- Restrict `CI_JOB_TOKEN` access to the projects that actually need it (the
  job token allowlist).

## `build`

Define `IMAGE` once in top-level `variables:` (`$CI_REGISTRY_IMAGE` when
using the GitLab registry, otherwise the organisation's registry). Tags and
OCI labels derive from `$CI_COMMIT_TAG`, `$CI_COMMIT_SHA` and
`$CI_PROJECT_URL`, and are computed in one place.

- One job with a `parallel: matrix` over `ARCH` and a per-arch runner in
  `tags:`. Ask the user which runner tags exist.

  ```yaml
  parallel:
    matrix:

From leroyguillaume/claude, MIT.

More from leroyguillaume/claude