ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:
  # The pages describe a library that lives in another repository, so a change *there* can
  # make a page here wrong without anything here changing. `CTRLRun/ctrlrun`'s own CI sends
  # this event on a push to its main branch, and the run below checks these pages against
  # that commit. Without it the split would have turned a red check into a slow drift.
  repository_dispatch:
    types: [library-changed]
  # And a weekly floor, so a dispatch that never arrives -- a token expiring, a workflow
  # edited -- surfaces as a red run rather than as silence.
  schedule:
    - cron: "17 6 * * 1"

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          path: ctrlrun-docs

      # Which commit of the library to check these pages against. A dispatch names one. A
      # branch here is checked against the `CTRLRun/ctrlrun` branch of the same name when
      # there is one, because that is the pair: a change there that alters a docstring or a
      # `--help` comes with a branch here, regenerated against it, and each is checked against
      # the other (that repository's `docs` job does the mirror image). Everything else is
      # checked against `main`, so the pages on `main` match the library's `main` at all times.
      #
      # Before this every branch here was checked against the library's `main`, and a page
      # regenerated for a commit that had not merged yet was red until it did -- by
      # construction, for the whole of a release cycle. The fallback is `main` and not a skip,
      # for the reason `_core.py` raises: red for a reason beats green for none.
      #
      # The branch name reaches the shell through `env:`, never inline in the script, so a
      # branch called `$(...)` is a string here and not a command. The match is exact and
      # fixed-string: `ls-remote` matches a pattern against the tail of a ref, and `.` in a
      # version would be a regex wildcard.
      - name: Pick the ctrlrun ref
        id: ctrlrun
        env:
          DISPATCHED: ${{ github.event.client_payload.sha }}
          BRANCH: ${{ github.head_ref || github.ref_name }}
        run: |
          set -eu
          if [ -n "$DISPATCHED" ]; then
            echo "ref=$DISPATCHED" >> "$GITHUB_OUTPUT"
            echo "ctrlrun at $DISPATCHED, the commit the dispatch named"
          elif git ls-remote --heads https://github.com/CTRLRun/ctrlrun.git "refs/heads/$BRANCH" \
              | cut -f2 | grep -qxF "refs/heads/$BRANCH"; then
            echo "ref=$BRANCH" >> "$GITHUB_OUTPUT"
            echo "ctrlrun at $BRANCH, the branch of the same name"
          else
            echo "ref=main" >> "$GITHUB_OUTPUT"
            echo "ctrlrun at main: it has no branch named $BRANCH"
          fi

      # The library these pages document. The checks read it -- a page that says the CLI
      # prints X is only true if the CLI prints X -- and `tools/docs_audit/_core.py` raises
      # when it is absent rather than skipping, so a checkout that failed to happen is a red
      # run and not a green one that verified nothing.
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          repository: CTRLRun/ctrlrun
          ref: ${{ steps.ctrlrun.outputs.ref }}
          path: ctrlrun

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.12"

      - name: Install
        run: |
          python -m pip install --upgrade pip
          # The library itself, because the reference pages are rendered from its docstrings
          # and its `--help`, and the checks import it to compare.
          pip install -e "./ctrlrun[dev,gateway,otel,identity]"
          pip install ruff mypy pytest griffe pyyaml

      # One script, called here and by a developer before pushing, so "it passed locally" and
      # "it passed in CI" cannot come to mean different things.
      - name: check
        working-directory: ctrlrun-docs
        env:
          CTRLRUN_SOURCE: ${{ github.workspace }}/ctrlrun
        run: ./scripts/check.sh

      # The drift checks, named individually because `STYLE.md` says the CI job runs them and
      # `test_ci_runs_the_three_checks_and_the_drift_check` reads this file to prove it.
      # A guard CI does not run is prose.
      #
      # `render_readiness.py --check` joined them on 2026-09-14. Its own docstring called it
      # "what CI runs" and CI did not run it, which is the same sentence one level up: the test
      # count is the one figure on the site that is a measurement rather than a claim, and the
      # pytest check on it compares the embedded block against the *stored* `readiness.json`
      # rather than against the suite, so the two agreed with each other while both drifted away
      # from the library. It cannot flap between a paired kernel and docs merge, because the
      # count is a **floor**: it fails when the suite has fewer tests than the page claims, and
      # passes when it has more.
      - name: The documentation audit
        working-directory: ctrlrun-docs
        env:
          CTRLRUN_SOURCE: ${{ github.workspace }}/ctrlrun
        run: |
          python tools/docs_audit/snippets.py
          python tools/docs_audit/lint.py
          python tools/docs_audit/links.py
          python tools/docs_audit/render_capabilities.py --check
          python tools/docs_audit/render_readiness.py --check