gh-clean 0.1.0

Remote GitHub branch cleanup reporting tool

gh-clean

gh-clean is a remote GitHub branch cleanup tool. It evaluates branches using GitHub repository state, produces a report, and can delete branches after re-validating that they are still safe to remove.

Requirements

• Python 3.9+
• GitHub CLI installed
• gh auth login completed for the target repositories

gh-clean currently uses gh for GitHub API access and authentication.

Install

With uv

Install once:

uv tool install gh-clean

Run without installing globally:

uvx gh-clean report --repo OWNER/REPO

With pipx

pipx install gh-clean

Authenticate

Before using the tool:

gh auth login

If your org requires SAML SSO, authorize the current gh token for that organization as needed.

Repository config

The target repository must contain a root .gh-clean.yml file with a non-empty protected_branches list.

Example:

protected_branches:
  - main
  - staging
  - production

This list is checked in addition to GitHub branch protection rules and rulesets.

If you need a one-off run before the config is committed, you can bypass the remote file with a CLI override:

gh-clean report --repo OWNER/REPO --protected-branches main,staging,production

Usage

Generate a report:

gh-clean report --repo OWNER/REPO
gh-clean report --repo OWNER/REPO --format json
gh-clean report --repo OWNER/REPO --protected-branches main,staging,production

Add extra protected branches at runtime:

gh-clean report --repo OWNER/REPO --exclude develop --exclude release/v2

Delete from a prior report with re-validation:

gh-clean report --repo OWNER/REPO --format json > report.json
gh-clean delete --repo OWNER/REPO --input report.json --recommendation delete-candidate --dry-run
gh-clean delete --repo OWNER/REPO --input report.json --recommendation delete-candidate
gh-clean delete --repo OWNER/REPO --input report.json --recommendation delete-candidate --protected-branches main,staging,production

Delete specific branches:

gh-clean delete --repo OWNER/REPO --branch feature/foo --branch feature/bar --dry-run

Override only the merged-tip mismatch soft veto:

gh-clean delete --repo OWNER/REPO --branch feature/foo --force-merged-tip-mismatch --dry-run

Development

Run directly from the checkout:

python3 -m gh_clean report --repo gh-clean-sandbox/sandbox
uv run gh-clean report --repo gh-clean-sandbox/sandbox

Run tests:

python3 -m unittest discover -s tests -v