Skip to content
Ahmad Ammar

5. Continuous integration

5.1 What the terms mean

  • Continuous integration (CI) runs your checks automatically on every change, on a clean machine.

  • Continuous delivery or deployment (CD) then publishes the result, but only if the checks pass.

A clean machine catches the classic fault of a project that only works on your own computer.

5.2 A first workflow

Save this in your repository as .github/workflows/tests.yml:

tests.yml

# Save as .github/workflows/tests.yml in a GitHub repository.
name: tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install pytest
      - run: python -m pytest

Reading it line by line:

  • on says when to run: on each push and pull request.

  • runs-on picks a fresh virtual machine.

  • steps run in order. uses runs a ready-made action, and run runs a command.

  • If any step fails, the run fails, and GitHub shows a red cross.

See the results under the repository's Actions tab. Read the failing step's log from the bottom up, and find the first real error.

These are the Actions tab and one run from my pamphlet project, with the account name hidden. A green tick means every step passed.

The Actions tab lists each run with its outcome and how long it took.

The Actions tab lists each run with its outcome and how long it took.

One run: the deploy job starts only after the build job passes.

One run: the deploy job starts only after the build job passes.

5.3 From testing to publishing

A publishing workflow adds a job that only runs after the checks succeed. This is how my pamphlet's workflow works:

  1. Install Pandoc, LaTeX and a browser.

  2. Run the equation tests.

  3. Rebuild every page and PDF from source.

  4. Check links and numbers.

  5. Open every page in a browser, and test what readers see.

  6. Publish, only if all of that passed. Otherwise, the old site stays up.

5.4 Practical advice

  • Pin versions of tools that affect output, such as python-version: "3.12".

  • Keep secrets out of files. Store them in the repository's settings as encrypted secrets.

  • Keep private work private. A public workflow's logs are public.

  • Watch the time. Slow checks get ignored, so run the quickest first.

5.5 Hooks: checks before you push

A Git hook runs a script at a moment such as a commit. A file at .git/hooks/pre-commit can block a commit containing a secret or broken code, and a pre-push hook does the same before sending work online. Hooks aren't copied with a repository, so each person must install them. For a shared setup, look at the pre-commit tool.

5.6 Scheduled checks

CI can also run on a timetable, and on your own computer, Windows Task Scheduler or cron can run a daily health report that emails you when something changes. Keep alerts rare, because people stop reading frequent ones.