Skip to content

feat(github): opt in to deleting a merged pull request's head branch - #84

Open
PsiACE wants to merge 1 commit into
mainfrom
feat/merged-branch-cleanup
Open

PsiACE wants to merge 1 commit into
mainfrom
feat/merged-branch-cleanup

Conversation

@PsiACE

@PsiACE PsiACE commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Purpose

Landing had no way to remove a pull request's head branch after a successful merge. This adds an explicit, off-by-default policy that does exactly that, reusing the pull_request event path the GitHub adapter already handles. No daemon, poller, webhook receiver, or extra workflow is introduced.

Behavior: delete-merged-branch is a new GitHubSettings policy field defaulting to false, surfaced as a new --delete-merged-branch/--no-delete-merged-branch CLI option (preserving explicit INPUT_*/CLI precedence) and as an action.yml input with an empty default, which defers to the documented default false.

When enabled, a pull_request event with action closed performs cleanup in github_event after admission and before delegation. Cleanup re-reads the pull request and deletes nothing unless GitHub still reports state: closed and merged: true, so a closed-but-unmerged, abandoned, or declined action is skipped. It only touches the merged pull request's own head branch inside the current repository, so a fork pull request never affects the fork. It skips the default branch, protected branches, and any head repository that is not the current repository. It compares the live branch tip against the merged head SHA and skips a branch that advanced after the merge. An already-absent branch is a successful no-op, while authorization and API errors raise and fail the invocation instead of reporting success. Merge status is never mutated or misreported. The step uses the runner's existing prepared gh credentials and adds no scopes. It prints its outcome to stderr and the step summary, creates no action record, and delegates no model work.

Validation

  • uv run python -m pytest tests/test_github.py tests/test_configuration.py -q → exit 0, 80 passed.
  • uv run python -m pytest tests -q → exit 0, 158 passed.
  • uv run ty check → exit 0, "All checks passed!".
  • uv run pre-commit run --all-files → exit 0.
  • make docs-test → exit 0.

New tests in tests/test_github.py cover: off-by-default leaving behavior unchanged; opt-in deletion of the correct repo/branch without delegating model work; unmerged, fork, default-branch, protected, advanced, and already-absent branches; and API/auth failures reported as failures rather than success. They use the existing gh emulator fixture, extended only to record branch reads and ref deletions. No real remote branch is touched.

Compatibility

Opt-in only. With the setting unset or false, the delegation path for these events is unchanged. Users relying on GitHub's repository-wide "automatically delete head branches" setting are unaffected; that setting is global to the repository and is documented as a separate, non-Landing option.

AI assistance

Implemented with an AI coding agent (harness and model not further identifiable from this session).

Add a delete-merged-branch policy that removes a merged PR's own head
branch. It runs only on a pull_request closed event whose pull request is
actually merged, verifies the head branch still matches the merged head
SHA, and skips forks, the default branch, protected branches, and branches
owned by another repository. An absent branch is a no-op; API and
authorization failures fail the invocation. Empty Action input defers to
the documented default false.

@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.

One non-blocking documentation gap inline. The implementation matched the documented contract in focused probes: default off, explicit CLI override over the input, skips for unmerged, fork, default, protected and advanced heads, absent-branch no-op, and authorization failure rather than a success report.

Comment thread docs/guides/github.md

## Delete merged head branches

Set `delete-merged-branch: true` to remove a pull request's own head branch once that pull request is actually merged. Cleanup runs only for a `pull_request` event with action `closed` and a merged pull request; a closed but unmerged pull request, a declined or abandoned action, and an unmerged candidate leave branches untouched. The Action input is empty by default, so an empty or omitted input uses the documented default `false`; an explicit `true` or `false` wins.

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.

Setting this input alone does not enable the feature for the workflow in Get started: that review.yml triggers pull_request with the default types (opened, synchronize, reopened) and grants contents: read, so no closed event ever reaches the Action and nothing is deleted, with no diagnostic. Once types: [closed] is added, the git/refs/heads/... -X DELETE call needs contents: write; without it the step fails on every merge instead of skipping.

State both prerequisites here, as the security-alert section above does for vulnerability-alerts: read: add closed to the pull_request trigger types and grant contents: write through the workflow token or the prepared identity, and note that a token without it fails the invocation rather than skipping.

@github-actions

Copy link
Copy Markdown
Contributor

Landing: allow · 15e9cbb

Non-blocking documentation gap in the new section: github.md:96 — the workflow needs types: [closed] and contents: write, which the section never states.

This branch has not been deployed

No deployments
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.

1 participant