Reading and writing .gitlab-ci.yml

Why this matters

The file is the pipeline. Reading it tells you exactly what will be checked, which lets you run the same checks locally; writing a small piece of it is a realistic and welcome contribution, because documentation checks are usually nobody's job.

The real file

This site's own .gitlab-ci.yml, entire. It has three jobs: one that checks the committed HTML is up to date, one that checks every link, and one that publishes the site.

stages:
  - check
  - deploy

default:
  image: python:3.13-slim

build-is-current:
  stage: check
  script:
    - pip install --quiet markdown
    - python tools/build.py
    - git diff --exit-code || (echo "The committed HTML is out of date. Run 'python tools/build.py' and commit the result." && exit 1)

links:
  stage: check
  script:
    - pip install --quiet markdown
    - python tools/build.py
    - python tools/check-links.py

pages:
  stage: deploy
  script:
    - pip install --quiet markdown
    - python tools/build.py
    - mkdir -p public
    - cp -r index.html assets playground start reference labs [0-9]* public/
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Line by line

stages lists the phases in order. Everything in check runs before anything in deploy, and if any check job fails, deploy never starts.

default: with image: sets the container every job starts from, unless a job overrides it. python:3.13-slim is a small official Python image; the slim variants save minutes of download time.

Each top-level name is a job. build-is-current, links and pages are the three here. The names are yours to choose, except that pages is special on GitLab: it is the job whose artifact gets published.

script is a list of shell commands, run in order in a fresh container. If any command exits non-zero, the job fails. These are ordinary commands you can run yourself, which is the most useful thing to know about the whole file.

artifacts: paths: keeps files after the job ends. For pages, the public folder is what GitLab serves.

rules: decide whether a job runs at all. Here, pages runs only when the branch is the project's default branch, so a merge request runs the checks but never publishes.

The clever line is in build-is-current. The site's HTML is committed, so a contributor could edit a lesson and forget to rebuild. The job rebuilds and then asks Git whether anything changed:

$ python tools/build.py
$ git diff --exit-code

git diff --exit-code exits 1 when there are differences, which fails the job with a message telling the contributor exactly what to do.

The keywords you will meet elsewhere

Adding a check of your own

A documentation check is the natural first contribution. Adding a job is four lines:

spelling:
  stage: check
  image: node:20
  script:
    - npx --yes cspell "docs/**/*.md"
  allow_failure: true

Two deliberate choices there. The job overrides the default image, because the tool is a Node package. And allow_failure: true means it reports without blocking, which is the polite way to introduce a new check to a team: everyone sees the result for a few weeks, the existing problems get cleaned up, and only then does it become blocking.

Testing a change before pushing

Three levels, in increasing order of effort:

1. Run the script lines yourself. They are ordinary commands.
2. Use the platform's linter: Build → Pipeline editor → Validate, which checks the YAML and the structure without running anything.
3. Push to a branch. A pipeline change is like any other change: it goes on a branch and through a merge request, and the pipeline that runs on that branch is the new one.

The pipeline editor is worth knowing about: it catches indentation mistakes, which are the most common YAML error and the most annoying to debug from a failed run.

How to do it

$ cat .gitlab-ci.yml
$ python tools/build.py
$ python tools/check-links.py

Common mistakes

• Tabs, or wrong indentation. YAML rejects tabs; nesting decides meaning.
• Assuming a job runs everywhere. Check its rules.
• A new check added as blocking, which stops everyone's work until the backlog of existing problems is cleared.
• Forgetting the job needs its tools installed. A fresh container has nothing but the image.
• Editing the file directly on the default branch, which is both risky and usually blocked.
• Expecting the runner to see uncommitted files.