Skip to content

docs(github): recommend GitHub's native merged branch cleanup - #84

Closed
PsiACE wants to merge 4 commits into
mainfrom
feat/merged-branch-cleanup
Closed

PsiACE wants to merge 4 commits into
mainfrom
feat/merged-branch-cleanup

Conversation

@PsiACE

@PsiACE PsiACE commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Purpose

Landing's delegated work leaves short-lived branches behind: dependency updates open draft PRs on fresh branch names, and a repair may push to a candidate's own branch. Once those PRs merge, the head branches accumulate.

GitHub already solves this at the repository level. This PR documents that, and removes the earlier attempt to reimplement it inside Landing.

What changed

Documentation only: docs/guides/github.md gains a short "Clean up merged branches" section recommending GitHub's Automatically delete head branches repository setting, with the settings path and the reason it fits this workload: deletion happens server-side on merge, so it costs no workflow run, no runner minutes, and no extra token scope.

The section states the real scope. The setting is repository-wide, so every merged pull request loses its head branch, not only those Landing opened; fork heads and the default branch are unaffected. It also says plainly that a workflow cannot enable it, and that Landing does not change repository settings.

Why the earlier implementation was dropped

An earlier revision of this branch added a delete-merged-branch policy, an Action input, and a companion workflow. It was withdrawn for two reasons:

  • It was not actually Landing-specific. Cleanup keyed only on "is this PR merged", so it behaved as a slower, runner-consuming equivalent of the native setting while claiming narrower scope.
  • Triggering it meant a separate closed-only workflow, because adding closed to Main's pull_request types would also rerun the entire native check matrix on every merge. That is real cost for something GitHub does for free.

Net effect of the branch against main is one documentation section: 14 added lines, no source, Action, test, or workflow change.

Validation

uv run zensical build -s exits 0 with no issues.

Not run: no source change to test, so the suite was not rerun for this revision, and no repository setting was changed. Enabling the recommended setting remains a manual repository action.

AI assistance

AI-assisted implementation and review; the recorded source and validation results were checked by the contributing workflow.

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 Resolved
@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Landing: allow · d72ac10

Non-blocking: the new section's opt-out sentence asks for controls GitHub doesn't offer in that order (inline finding); the recommended setting and its scope are accurate.

@PsiACE PsiACE changed the title feat(github): opt in to deleting a merged pull request's head branch docs(github): recommend GitHub's native merged branch cleanup Nov 17, 2026

@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 finding inline. The recommendation itself checks out: the settings path matches GitHub's "Managing the automatic deletion of branches", and the repository-wide scope matches our own delete_branch_on_merge: false default. No source, workflow or Action change to test in this revision.

Comment thread docs/guides/github.md

The setting is repository-wide: every merged pull request loses its head branch, not only the ones Landing opened. That is usually what you want, since a merged branch has no further purpose. Enable it by hand in repository settings; Landing does not toggle repository settings, and a workflow cannot enable this for you.

If you want to keep a merged branch for reference, merge that pull request with auto-delete disabled or restore the branch before it is removed.

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.

This opt-out cannot be followed as written. There is no per-pull-request way to merge with auto-delete disabled: GitHub documents the switch as a repository setting (the delete_branch_on_merge repository field), and neither the merge box nor the pull request object exposes a per-PR override, so keeping one branch this way means disabling the setting for the whole repository. The second half is inverted as well: "Restore branch" is an action on a closed pull request whose head branch is already deleted, so there is nothing to restore while the branch still exists.

State the two workable options instead: disable the repository setting before merging, or restore the head branch from the merged pull request afterwards. GitHub's deletion page also notes that branch protection rules and rulesets can block automatic deletion, which is the per-branch lever if a long-lived branch must survive merges.

@PsiACE

PsiACE commented Nov 17, 2026

Copy link
Copy Markdown
Member Author

Closing: GitHub's native 'Automatically delete head branches' setting covers this, so the documentation note is not worth maintaining.

@PsiACE PsiACE closed this Nov 17, 2026
@PsiACE
PsiACE deleted the feat/merged-branch-cleanup branch November 20, 2026 17:06
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