Skip to content

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.

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.

  1. Open the pr-gates run of the pull request and find the job that failed.
  2. If changes failed, re-run the failed jobs. The job reads the file list from the GitHub API, so a failure is usually an API error.
  3. 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 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.

  1. Open the run that the newest comment links, or the issue body if there is no comment. Find the member that failed.
  2. 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 changes job, in the same pull request as the fix.
  3. If two pull requests broke main together, fix main in a new pull request. The ruleset does not require an up-to-date branch, so each pull request passed alone.
  4. 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.