Skip to content

Design: pr-gates runs what changed

See openspec/changes/archive/2026-10-03-pr-gates-run-what-changed/proposal.md, section Why, for the measurements. The current state that shapes the approach:

  • pr-gates.yml has 10 member jobs and the aggregate pr-gates. The aggregate carries if: always(), lists every member in needs: and runs re-actors/alls-green. Only the aggregate has a job-level name: key, and tools/pr-gates/required-context-liveness.sh compares those keys with the ruleset in tf/core-services/github.tf.
  • The docs build reads docs/** and website/**. website/src/content/docs is a symbolic link to ../../../docs, and docs/ holds no symbolic links.
  • apps/dns-control/tools/proto.sh runs every buf and Go step in the golang image of the Dockerfile. It mounts $HOME/.cache/dns-control-proto as /cache for GOMODCACHE and GOCACHE. The runner home is new on each run, so go tool buf compiles buf every time.
  • Both Namespace runner profiles already attach a cache volume. The job logs show it, but no workflow mounts a path on it.
  • #2653 removed tools/dns-aaaa-publish and its step on 2026-10-02. The dns-tool-suites job now runs only the dns-network-handover suite.
  • tools/docs-audit/audit.py imports fm_title from llms_coverage.py.
  • argocd/app-configs/clickstack-alerts/bootstrap-script.yaml names tools/clickstack-alert-lint/lint.py in comments and in two runtime error strings. docs/operations/alerting.md lists the lint as the second of three checks for an alert change.
  • pyproject.toml lists tools/dns-network-handover as the only entry of pythonpath and testpaths, and in the ruff per-file ignores.

Goals:

  • A member runs only when the pull request changes a path that the member reads.
  • A wrong or missing filter becomes visible within one day.
  • The required contexts and the liveness script do not change.

Non-Goals:

  • The jdx toolchain, hk and the lint member. Change jdx-toolchain owns them.
  • The apt-get install ripgrep steps. After this change they run on about 2% of pull requests, and jdx-toolchain replaces them with mise.
  • Image builds on main, Dockerfile cache mounts and tag guards. Change image-release-hygiene owns them.
  • Moving the source-gates checks into a Go linter.

D-1: A changes job with dorny/paths-filter

Section titled “D-1: A changes job with dorny/paths-filter”

The changes job runs dorny/paths-filter, pinned by commit SHA. On pull_request the action reads the file list of the pull request from the API, so the job needs no checkout. It needs pull-requests: read.

The job has one output for each area and one output all. all is true when the event is not pull_request, or when the pull request changes .github/workflows/pr-gates.yml. It is also true when the pull request changes 3000 files or more, because the API lists at most 3000 files and the action does not report a cut list. Each member carries if: needs.changes.outputs.all == 'true' || needs.changes.outputs.<area> == 'true'.

Alternatives considered:

  • An in-repository script over git diff --name-only. It needs a checkout with history, and it is code to maintain for a solved problem.
  • tj-actions/changed-files, which pr-review.yml uses today. A supply-chain attack compromised it in March 2025, and jdx-toolchain removes it.
  • A YAML anchor that adds the workflow file to every filter. The all output says the same thing once, and the scheduled run needs it anyway.
Output Paths Members
docs docs/**, website/** docs-build
dnscontrol apps/dns-control/** dns-control-suite, dns-control-proto, changelog-fragment
hlassets apps/hl-assets-uploader/** test-amd64, test-arm64, source-gates, changelog-fragment
changelog .changes/**, tools/pr-gates/changelog-fragment.sh changelog-fragment
policy argocd/app-configs/temporal-server/node-gateway/policy/** temporal-gateway-policy
ruleset tf/core-services/github.tf, tools/pr-gates/** required-context-liveness
fixtures tools/gate-fixtures/**, argocd/app-configs/clickstack/watchdog-cronjob.yaml gate-fixtures
tools mise.toml, mise.lock docs-build, required-context-liveness, source-gates
all .github/workflows/pr-gates.yml, or any event other than pull_request every member

Each row lists every path its members read. A member that starts to read a new path adds it to its row in the same pull request.

pr-gates keeps if: always(), its name: key and every member in needs:. It also lists changes in needs:. It passes every member, and not changes, to alls-green as allowed-skips. A member skipped because changes failed therefore cannot turn the aggregate green, because changes itself is red.

pr-gates.yml gains schedule: - cron: '23 5 * * *' and workflow_dispatch. Both set all to true, so every member runs against the head of main. The minute is off the hour, which avoids the queue at the top of each hour.

A job nightly-alert runs with if: always() && github.event_name != 'pull_request' and needs: [pr-gates]. A manual run with workflow_dispatch therefore reports the same way as the scheduled run. It has no job-level name: key and is not a member of the aggregate. It is the only job with issues: write. It uses gh with GITHUB_TOKEN:

Result of pr-gates Open issue titled nightly pr-gates is red Action
failure none Create the issue with the label alert and a link to the run
failure one Comment with a link to the run
success one Comment that the run is green, then close the issue
success none Nothing

The job looks for the issue among the open issues with the label alert, by its title and by its author, the github-actions bot. The title lets the label serve other alerts later. The author check ignores an issue that a person opens with the same title. The label is a github_issue_label resource in tf/core-services/github.tf, beside the ruleset that the same provider manages. The alternative, gh label create --force inside the job, makes the workflow a second writer of repository settings. The label endpoints need the Issues write permission, so the fzymgc-terraform App holds it beside Administration.

dns-control-proto runs namespacelabs/nscloud-cache-action, pinned by commit SHA, with path: ~/.cache/dns-control-proto, after checkout and before proto.sh check. proto.sh does not change, so buf and Go still run inside the pinned golang image with no network. It runs the container as the user of the runner, so the cache files do not belong to root.

Each machine of the Namespace fleet holds its own copy of a cache volume. A job gets a hit only on a machine that already holds the data, and each successful run commits the data on one more machine. Early runs therefore miss and compile buf as before. A miss costs no time.

Namespace Artifacts was rejected. It is object storage by path, with no cache key, so a cache on it is a hand-built copy of actions/cache. actions/cache was also not chosen. After PR 1 the member runs on few pull requests, and a restore and a save on each run cost more than they save.

The workflow keeps the push trigger on main with its path filter, and workflow_dispatch. It loses the pull_request trigger, the branch slug step, the preview deploy, the preview comment, the llms_coverage.py step, the pull-requests: write permission and the bot exclusion. A push to main holds only merged code, so the exclusion guards nothing. It gains concurrency: { group: docs-deploy, cancel-in-progress: true }, so the newest build deploys last.

  • fm_title moves from llms_coverage.py into the docs_audit package, and audit.py imports it from there. tools/docs-audit/ stays as a local tool.
  • The two error strings in bootstrap-script.yaml stop naming the lint file. The runtime check stays. docs/operations/alerting.md describes two checks for an alert change, not three.
  • pyproject.toml loses the dns-network-handover and clickstack-alert-lint entries. The pytest testpaths and pythonpath become empty, so the pytest section goes, and the dns-tool-suites job goes with its last suite.
  • .github/WORKFLOWS.md describes the workflows that remain.

The banner comments of pr-gates.yml hold 188 of its 462 lines. Each invariant they explain is a requirement in openspec/specs/ci-pr-gates/spec.md. The workflow keeps a one-line comment at each place where an edit can break a constraint, for example “no job-level name: key: that makes a required context”.

  • [A filter misses a path that a member reads, and a broken change merges green] → The nightly run executes every member against main, and a red run opens the alert issue within one day. D-2 keeps each read-set in one table.
  • [Two pull requests pass on their own and break main together] → The ruleset does not require an up-to-date branch today, so this risk exists already. The nightly run now catches it.
  • [dorny/paths-filter is a third-party action with read access to the pull request] → Pin it by commit SHA, and give the changes job only pull-requests: read.
  • [A pull request branch writes a bad entry to the shared cache volume] → Only proto.sh check reads that cache, and every pull request comes from a branch in this repository.
  • [The cache volume misses until its data reaches enough machines] → A miss costs no time. Issue #2668 measures the hit after a week of runs. If hits do not come, switch to actions/cache.
  • [A scheduled workflow stops after 60 days with no repository activity] → This repository merges pull requests every day, so the schedule stays active.
  1. PR 1 merges. main-cluster-core-services applies the alert label on merge. The next nightly run proves D-4 and D-5. To test D-5 before that, run the workflow by hand with gh workflow run pr-gates.yml --ref main.
  2. PR 2 merges. A week of dns-control-proto runs after it shows whether the cache holds.
  3. PR 3 merges after PR 1.

Rollback: revert the merge commit of the pull request with git revert <sha> on a new branch and merge that pull request. For PR 1, the revert also removes the github_issue_label, and main-cluster-core-services deletes the label on merge.