Design: pr-gates runs what changed
Context
Section titled “Context”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.ymlhas 10 member jobs and the aggregatepr-gates. The aggregate carriesif: always(), lists every member inneeds:and runsre-actors/alls-green. Only the aggregate has a job-levelname:key, andtools/pr-gates/required-context-liveness.shcompares those keys with the ruleset intf/core-services/github.tf.- The docs build reads
docs/**andwebsite/**.website/src/content/docsis a symbolic link to../../../docs, anddocs/holds no symbolic links. apps/dns-control/tools/proto.shruns every buf and Go step in the golang image of the Dockerfile. It mounts$HOME/.cache/dns-control-protoas/cacheforGOMODCACHEandGOCACHE. The runner home is new on each run, sogo tool bufcompiles 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-publishand its step on 2026-10-02. Thedns-tool-suitesjob now runs only thedns-network-handoversuite. tools/docs-audit/audit.pyimportsfm_titlefromllms_coverage.py.argocd/app-configs/clickstack-alerts/bootstrap-script.yamlnamestools/clickstack-alert-lint/lint.pyin comments and in two runtime error strings.docs/operations/alerting.mdlists the lint as the second of three checks for an alert change.pyproject.tomlliststools/dns-network-handoveras the only entry ofpythonpathandtestpaths, and in the ruff per-file ignores.
Goals / Non-Goals
Section titled “Goals / Non-Goals”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-toolchainowns them. - The
apt-get install ripgrepsteps. After this change they run on about 2% of pull requests, andjdx-toolchainreplaces them with mise. - Image builds on
main, Dockerfile cache mounts and tag guards. Changeimage-release-hygieneowns them. - Moving the
source-gateschecks into a Go linter.
Decisions
Section titled “Decisions”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, whichpr-review.ymluses today. A supply-chain attack compromised it in March 2025, andjdx-toolchainremoves it.- A YAML anchor that adds the workflow file to every filter. The
alloutput says the same thing once, and the scheduled run needs it anyway.
D-2: The filters
Section titled “D-2: The filters”| 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.
D-3: The aggregate
Section titled “D-3: The aggregate”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.
D-4: The nightly run
Section titled “D-4: The nightly run”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.
D-5: The alert job
Section titled “D-5: The alert job”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.
D-6: The proto cache
Section titled “D-6: The proto cache”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.
D-7: docs.yml
Section titled “D-7: docs.yml”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.
D-8: The removals
Section titled “D-8: The removals”fm_titlemoves fromllms_coverage.pyinto thedocs_auditpackage, andaudit.pyimports it from there.tools/docs-audit/stays as a local tool.- The two error strings in
bootstrap-script.yamlstop naming the lint file. The runtime check stays.docs/operations/alerting.mddescribes two checks for an alert change, not three. pyproject.tomlloses thedns-network-handoverandclickstack-alert-lintentries. The pytesttestpathsandpythonpathbecome empty, so the pytest section goes, and thedns-tool-suitesjob goes with its last suite..github/WORKFLOWS.mddescribes the workflows that remain.
D-9: Comments and the spec
Section titled “D-9: Comments and the spec”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”.
Risks / Trade-offs
Section titled “Risks / Trade-offs”- [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 thealertissue within one day. D-2 keeps each read-set in one table. - [Two pull requests pass on their own and break
maintogether] → The ruleset does not require an up-to-date branch today, so this risk exists already. The nightly run now catches it. - [
dorny/paths-filteris a third-party action with read access to the pull request] → Pin it by commit SHA, and give thechangesjob onlypull-requests: read. - [A pull request branch writes a bad entry to the shared cache volume] → Only
proto.sh checkreads 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.
Migration Plan
Section titled “Migration Plan”- PR 1 merges.
main-cluster-core-servicesapplies thealertlabel on merge. The next nightly run proves D-4 and D-5. To test D-5 before that, run the workflow by hand withgh workflow run pr-gates.yml --ref main. - PR 2 merges. A week of
dns-control-protoruns after it shows whether the cache holds. - 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.