PR Gates Operations
pr-gates is the required check on main. .github/workflows/pr-gates.yml produces it. This page
says what to do when the gate is red on a pull request and when the nightly run fails.
.github/WORKFLOWS.md lists the members and the paths that each one reads. The design is in
docs/engineering/specs/2026-10-02-pr-gates-run-what-changed-design.md.
How the gate decides what runs
Section titled “How the gate decides what runs”The changes job reads the file list of the pull request. A member job runs only when the pull
request changes a path that the member reads. Every member runs in these cases:
- The pull request changes
.github/workflows/pr-gates.yml. - The pull request changes 3000 files or more, because the API lists at most 3000 files.
- The run is the scheduled run at 05:23 UTC, or a manual run with
workflow_dispatch.
The pr-gates job passes when every member passed or skipped. If the changes job fails, every
member skips and pr-gates fails.
The gate is red on a pull request
Section titled “The gate is red on a pull request”- Open the
pr-gatesrun of the pull request and find the job that failed. - If
changesfailed, re-run the failed jobs. The job reads the file list from the GitHub API, so a failure is usually an API error. - If a member failed, fix the cause in the pull request.
If a check cannot go green and the change has to land, follow Merge past a blocked required check.
The nightly run is red
Section titled “The nightly run is red”The scheduled run executes every member against the head of main. If it fails, the
nightly-alert job opens one issue titled nightly pr-gates is red with the label alert. Each
later failure adds a comment that links its run. The next green run closes the issue. The job
matches only an issue that github-actions opened, so an issue that a person opens with the same
title does not count.
- Open the run that the newest comment links, or the issue body if there is no comment. Find the member that failed.
- If the member failed on a change that merged green, its filter missed a path. Add the path to
the filter of that member in the
changesjob, in the same pull request as the fix. - If two pull requests broke
maintogether, fixmainin a new pull request. The ruleset does not require an up-to-date branch, so each pull request passed alone. - If the runner or the network failed, re-run the failed jobs of the nightly run.
After the fix merges, run gh workflow run pr-gates.yml --ref main. A green manual run closes the
issue, so you do not have to wait for the next scheduled run.
If you close the issue by hand while main is red, the next red run opens a new issue.