Skip to content

fix(pr-pipeline): split branch cleanup into plan and delete jobs with an atomic delete - #10290

Merged
kyle-sexton merged 11 commits into
mainfrom
fix/issue-8958-branch-cleanup-hardening
Oct 27, 2026
Merged

kyle-sexton merged 11 commits into
mainfrom
fix/issue-8958-branch-cleanup-hardening

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

Closes #8958

Summary

The branch-cleanup job held contents: write while it read issue and pull request text, and its delete could not say which tip it expected, so a push landing between the re-read and the delete was removed. This splits the job and makes the delete check the tip on GitHub's side, per the decision record on #8958. Item 3 (stopped-run branches of closed issues) is already done on main and is closed there with that evidence; the test "a stopped lane run's branch is deleted once its issue closes" still passes.

Fix

  • .github/workflows/maintenance-delete-stale-branches.yml: two jobs.
    • plan (contents, issues, pull-requests read) evaluates every branch and uploads at most max-deletes-per-run candidates as branch-cleanup-candidates-<run>-<attempt>.
    • delete (contents: write, pull-requests: read) runs only when the plan listed something and the run is not a dry-run. It checks the kill switch again, downloads that list, re-reads each tip and its open pull requests, and deletes. It reads no issue or pull request text.
    • Each job checks out main with persist-credentials: false. No permission is added: the write grant moves to the job that reads no untrusted text, and issues: read leaves that job.
  • .github/scripts/branch-cleanup/cleanup.mjs:
    • STAGE=plan|delete. The plan stage's client refuses every request but GET, dry-run or not.
    • The delete is one GraphQL updateRefs per branch, with beforeOid set to the listed tip and afterOid all zeros, in place of DELETE git/refs/heads/<branch>. One branch per call, because GitHub applies a list atomically and one refused update would refuse them all.
    • The client throws on a GraphQL errors list returned with HTTP 200. A refused delete re-reads the tip: a moved tip is reported as skipped, and anything else as a failed delete.
    • The delete stage refuses a candidate list for another repository, over the configured cap, or with an entry outside the rule's shape (excluded branch, non-40-hex SHA, unknown rule, duplicate).
    • The call budget leaves the delete stage 1 + 5 calls per planned delete, so both jobs together stay within CALL_BUDGET (600).
  • docs/conventions/pr-pipeline/README.md, "Branch cleanup": describes the two jobs and the atomic delete, and drops the "the API takes no expected SHA" text.
  • .changes/pr-pipeline/fix-8958-branch-cleanup-split-5c2e7a19.md: patch fragment.

Sources:

  • GraphQL updateRefs: "RefUpdate.beforeOid specifies that the given reference needs to point to the given value before performing any updates"; "A value of 0000000000000000000000000000000000000000 can be used to delete a reference"; "All updates are performed atomically".
  • actions/download-artifact: "By default, the permissions are scoped so they can only download Artifacts within the current workflow run." So the delete job needs no actions: read.

Verification

  • node --test .github/scripts/branch-cleanup/*.test.mjs: 27 pass, 0 fail. New tests:
    • one updateRefs per branch, with beforeOid equal to the listed tip;
    • a tip that moved after the delete-time re-read is not deleted and is reported as skipped (the fake GitHub refuses a stale beforeOid with HTTP 200 and an errors list, as GitHub does);
    • the client throws on a 200 errors answer;
    • the plan client refuses a write;
    • the delete stage refuses a bad list;
    • per-job permission, kill-switch, checkout and dry-run checks in workflow.test.mjs.
  • actionlint and zizmor --offline on the workflow: no findings. Runner policy passed.
  • node --test .github/actions/resolve-config/callers.test.mjs .github/actions/log-api-budget/*.test.mjs: 273 pass. scripts/workflow-self-paths.test.sh: 35 pass. scripts/check-app-key-references.sh --check and scripts/check-changelog-fragments.sh --check are clean.
  • Not run: the live updateRefs delete against GitHub. Its refusal of a stale beforeOid rests on the docs quoted above.

Checks a person runs:

  • A manual run with dry-run: false on a disposable branch, to confirm the live delete and the ledger.

Related

🤖 Generated with Claude Code

kyle-sexton and others added 4 commits October 26, 2026 00:12
… an atomic delete

The plan job reads branches, issues and pull requests with a token that
writes nothing and hands at most max-deletes-per-run candidates to the
delete job as an artifact. The delete job alone holds contents: write,
reads no issue or pull request text, and refuses a list for another
repository, over the cap, or with an entry outside the rule's shape.

Each delete is one GraphQL updateRefs with beforeOid set to the listed
tip, so a push that lands after the delete-time re-read makes GitHub
refuse the delete; the branch is reported as skipped.

Closes #8958

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review 🔄 Running since 2026-10-26T14:37:57.859243Z b3801b9 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

claude-review: 1 inline finding(s) on b3801b990075b1e64b7f60c50606da5222821890; the summary is in this lane's pull request comment.

claude-lane: claude-review

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

claude-review reviewed 9ad9cf06280bd035cbdcbb2db8bd46f8db1e30ab: 0 finding(s), 0 as inline comments.

No blocking findings. I read the whole diff and checked the changed cleanup.mjs and the workflow against the head files. I did not run the tests or the live updateRefs delete. Everything below is from reading the code.

Closing issue #8958, acceptance criteria

  • The criterion that cleanup.mjs deletes through updateRefs with beforeOid set to the listed tip and afterOid all zeros is met. deleteRef sends the mutation and no DELETE git/refs/heads/<branch> call remains. Two tests would fail if it broke: "the delete sends one updateRefs per branch…" and "a tip that moved after the delete-time re-read is not deleted and is reported as skipped". The second one covers the skipped-tip case.
  • The criterion for the plan job and the delete job is met. plan holds contents, issues and pull-requests read, with no write grant. delete holds contents: write and pull-requests: read. The delete stage reads only the candidate list and calls no linkedIssues parse. workflow.test.mjs pins both permission sets and the stage names.
  • The criterion that "a stopped lane run's branch is deleted once its issue closes" still passes is not touched by this diff. The evaluate() rules are unchanged, and the plan-to-delete path in run() in the tests exercises it.

Checks

  • readList validates every candidate rule against RULES. Those four names match the ones evaluate() produces (lane-issue-closed, pr-merged, pr-merged-no-commits-ahead, pr-closed), so a real plan is never refused by the delete stage.
  • The call budget adds up. The plan job keeps deleteBudget(cap) = 1 + 5×cap back from its 600 calls. The delete stage's client is capped at deleteBudget(planned). Each candidate spends 3 re-read calls, 1 delete call and at most 1 tip re-read, so it stays inside that cap.
  • The workflow is consistent. The artifact name is fixed by the plan job's output, so a re-run of only the delete job still finds it. The download path and CANDIDATES_PATH agree. Both jobs check out with persist-credentials: false. The delete job re-checks the kill switch. A dry-run starts no delete job.
  • Because the delete job re-reads the tip and then sends beforeOid, GitHub refuses the delete if a push lands after the re-read.
  • The client throws on a GraphQL errors list returned with HTTP 200, and a test covers it.

Not verified: GitHub's refusal of a stale beforeOid, and GitObjectID accepting an all-zero afterOid. Both rest on the docs the PR quotes. The PR says it did not run the live delete either. The manual dry-run: false run on a disposable branch that the author asked for is the right check.

Cost: none. The change adds no paid resource and no permission, and it adds one extra job run per day that spends only GitHub Actions minutes already in use.

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review reviewed 9ad9cf06280bd035cbdcbb2db8bd46f8db1e30ab: 0 finding(s), 0 as inline comments.

No security issues found in this change.

critical-findings: 0

I read the whole diff and the PR context, plus excluded in rules.mjs and stillDeletable in cleanup.mjs. No changed file matches a trusted-path glob or a trust control. The workflow maintenance-delete-stale-branches.yml is not a listed control. The only pr-pipeline file touched is README.md, not pr-pipeline.yaml. No plugin manifest changed, so there are no manifest <field> lines. The PR context contains no embedded instructions. I did not consult the instruction exception register, because no standing instruction is removed or softened.

What I checked:

  • Permissions. The plan job drops to contents: read, issues: read, pull-requests: read. The delete job holds contents: write and pull-requests: read and no longer has issues: read. No grant is added, and the write grant moves to the job that reads no issue or PR text.
  • Plan client. The plan stage's client is forced to dryRun: true, so it refuses any non-GET request whatever DRY_RUN says.
  • Candidate list as a trust boundary. The list crosses jobs as an artifact scoped to the same run (actions/download-artifact reads only the current run by default). The delete stage re-validates it in readList:
    • the repository matches;
    • the count is within the cap read from main's config;
    • each branch is not the default, release/*, dependabot/* or gh-readonly-queue/*;
    • each SHA is 40-hex;
    • each rule is in an allowlist;
    • issue and PR numbers are positive safe integers;
    • there are no duplicate names.
      A tampered list therefore cannot widen what the delete job removes. Every ref it touches is built as refs/heads/<name>, so a tag or other ref cannot be named.
  • Injection. Branch names and SHAs reach GraphQL only as variables, never interpolated into the query. REST paths use refPath and encodeURIComponent.
  • Compare-and-delete. updateRefs with beforeOid makes GitHub check the tip and delete in one step. This removes the earlier race, where a push landing between the re-read and the delete was destroyed. The client treats an HTTP 200 with an errors list as a failure, so a refused delete is not recorded as done. On a refusal the code re-reads the tip, so a moved tip is reported as skipped and not as a failed delete.
  • Kill switch and checkout. Each job checks the kill switch, and the delete job checks it again before any read or write. Both jobs check out github.sha with persist-credentials: false, so no PR code runs with the write token.
  • Dry-run. A manual dry-run starts no delete job.
  • Third-party actions. The new upload-artifact and download-artifact steps are SHA-pinned.

Not verified: the live updateRefs refusal of a stale beforeOid rests on GitHub's documentation, as the PR states. The PR also asks a person to run one manual dry-run: false check on a disposable branch.

Spend: none beyond ordinary Actions minutes. This adds a second job in the existing workflow, with no billed resource or plan change.

kyle-sexton and others added 5 commits October 26, 2026 13:23
The write-ahead ledger line said deleted even when GitHub refused the
delete because the tip moved. A second line with notDeletedAt and the
reason now records that the branch still stands.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…header

The workflow header still said a deleted branch is restored from its
ledger SHA, without the second line a refused delete writes. It now says
a branch with a notDeletedAt line still stands and is not restored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

claude-review: 1 inline finding(s) on 662057d95626afc7d857ab4955a53e6d1e4c06fd; the summary is in this lane's pull request comment.

claude-lane: claude-review

kyle-sexton and others added 2 commits October 26, 2026 23:12
…re-run

The delete job runs npm ci, so it names npm-fetch.npmrc as npm's global
config, as the plan job does.

The plan job outputs the artifact name it uploaded under, and the delete
job downloads that name: re-running only a failed delete job keeps the
plan job's outputs from the attempt that uploaded the list, where the
delete job's own run_attempt named an artifact no attempt uploaded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kyle-sexton
kyle-sexton added this pull request to the merge queue Oct 27, 2026
Merged via the queue into main with commit a1ccd8e Oct 27, 2026
39 checks passed
@kyle-sexton
kyle-sexton deleted the fix/issue-8958-branch-cleanup-hardening branch October 27, 2026 06:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(pr-pipeline): harden the branch-cleanup job (atomic delete, plan/delete split, stopped-run branches)

1 participant