ci.yml

# ---------------------------------------------------------------------------
# GitHub Actions CI — THIN WRAPPER
# ---------------------------------------------------------------------------
# This workflow deliberately contains no build logic. It only:
#   1. checks out the code,
#   2. provides a Python interpreter,
#   3. runs `make ci`.
#
# `make ci` builds the repo-local virtualenv (.venv/) from that interpreter and
# installs the pinned `pre-commit` from requirements-dev.txt into it, exactly as
# a developer's `make setup` does — so there is nothing to install globally here.
#
# All actual checks live in the Makefile (`make ci`) and run identically on a
# developer laptop. To change WHAT runs in CI, edit the Makefile and
# .pre-commit-config.yaml — not this file. The only things that belong here are
# platform-specific concerns that cannot live in a portable script: triggers,
# the runner image, and prerequisite installation.
#
# Determinism: tool versions are pinned (Python below; `pre-commit` in
# requirements-dev.txt; hook versions via `rev` in .pre-commit-config.yaml).
# Bump them deliberately.
name: ci

on:
  # Trunk-based: `main` is the only long-lived branch. Feature branches are
  # short-lived and reach `main` only through a pull request, so the
  # pull_request trigger is the gate — it fires for a PR from ANY head branch,
  # which is why no head-branch list is needed here.
  #
  # The push trigger covers `main` only, deliberately: adding feature branches
  # would run the same commits twice (once for the push, once for the PR) for no
  # extra signal.
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  # The job id is the name GitHub reports this check under, so it is also the
  # `context` that .github/rulesets/*.json requires. Renaming it silently breaks
  # branch protection: the required check is never reported, and pull requests
  # wait on it forever. Change both together.
  ci:
    # Pinned rather than `ubuntu-latest`: that label is remapped to a new Ubuntu
    # release periodically, which would change the build environment underneath
    # you on GitHub's schedule instead of yours. Bump this deliberately.
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v7

      # Interpreter used to build .venv. Any version >= 3.10 works (see
      # MIN_PYTHON in the Makefile); it is pinned here only for reproducible
      # runs, not because the hooks need this exact version.
      - uses: actions/setup-python@v7
        with:
          python-version: "3.14"

      # Cache pre-commit hook environments keyed on the config so unchanged
      # hooks are not rebuilt on every run.
      - uses: actions/cache@v6
        with:
          path: ~/.cache/pre-commit
          key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}

      # The single entrypoint. Everything CI does is defined in the Makefile.
      - run: make ci