Skip to content

Clean up closed PR wiki preview branches #83

@coisa

Description

@coisa

Problem

Wiki preview branches such as pr-<number> are useful while a pull request is open, but they can remain in the wiki repository after the pull request is closed or merged. Over time, stale preview branches make the wiki repository harder to inspect and can confuse maintainers about which preview branches are still active.

Proposal

Update the wiki automation so PR-scoped wiki branches are removed when they are no longer needed, and add a periodic cleanup path that removes branches for pull requests that are already closed.

Goals

  • Delete the PR wiki branch after the pull request is closed and the accepted content has been promoted when appropriate.
  • Periodically scan wiki preview branches and remove branches whose matching pull request is already closed.
  • Keep the wiki master branch as the only canonical published branch after merge.
  • Make cleanup safe for branches that do not follow the pr-<number> naming convention.

Expected Behavior

When a pull request is merged, the workflow promotes the PR wiki branch content to the wiki master branch and then deletes the corresponding pr-<number> wiki branch. When a pull request is closed without merge, the corresponding preview branch is deleted without promoting it to master. A scheduled cleanup also removes leftover pr-<number> branches for already closed pull requests.

Implementation Strategy

Extend the wiki workflow logic to delete the PR preview branch after the close/merge flow completes. Add a scheduled cleanup job or workflow path that lists pr-<number> branches in the wiki repository, checks the related pull request state through GitHub APIs, and deletes branches only when the pull request is closed.

Requirements

  • The merge-to-master path must complete before deleting the preview branch for merged pull requests.
  • Closed, unmerged pull requests must have their wiki preview branch deleted without publishing to master.
  • Periodic cleanup must ignore branches that do not match pr-<number>.
  • Missing preview branches must not fail the workflow.
  • Workflow permissions must be limited to the operations needed to read pull requests and update wiki refs.
  • Documentation or troubleshooting notes must be updated if the cleanup changes the maintainer workflow.

Non-goals

  • Changing how wiki previews are generated for open pull requests.
  • Renaming the wiki master branch.
  • Deleting manually maintained wiki branches that are not PR preview branches.

Benefits

This keeps the wiki repository tidy, reduces stale preview state, and makes the PR preview lifecycle match the reports preview cleanup model.

Acceptance Criteria

Functional Criteria

  • A merged PR promotes its wiki preview content to master and deletes the matching pr-<number> branch afterward.
  • A closed, unmerged PR deletes the matching pr-<number> branch without publishing it to master.
  • A scheduled cleanup removes stale pr-<number> wiki branches whose pull requests are already closed.
  • Cleanup is idempotent when the branch is already missing.
  • Branches that do not match the PR preview naming convention are ignored.

Architectural / Isolation Criteria

  • Wiki workflow changes remain scoped to preview cleanup and publish lifecycle behavior.
  • API calls and shell commands fail clearly when authentication or permission problems prevent cleanup.
  • Tests, workflow validation, or documented manual verification cover merged, closed-unmerged, missing-branch, and orphan-branch scenarios.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

Status

Released

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions