delete-branches
✅ What does delete-branches do?
delete-branches deletes idle branches in GitHub repository.
exemptions: default branch, protected branches, head branches in PR, and user-specified exclude branches
⭐ Why switch to delete-branches?
- we reduce your supply chain risks with openssf best practices in our SDLC and operations.
- we share evidence of code coverage results in action (click Code Coverage » cron-tasks » badge-coverage).
- we can run using command line or GitHub Action Delete GitHub Branches.
🏃 Running delete-branches in GitHub action
Use the workflow examples below to create your own workflow inside .github/workflows/.
Example 1 - Summary (MOCK delete)
| Input | Workflow Spec | Notes |
|---|---|---|
scheduled run |
- cron: '30 17 * * *' |
Run daily at 5:30 pm UTC |
github token permissions |
contents: readpull-requests: read |
MOCK delete requires read permission |
dry-run |
true |
MOCK delete |
exclude-branches |
badges |
Branch badges is found and excluded |
max-idle-days |
10 |
Without new commits longer than 10 days |
Example 1 - Workflow (MOCK delete)
name: delete-github-branches
on:
schedule:
- cron: '30 17 * * *'
permissions:
contents: read
pull-requests: read
jobs:
delete-branches:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read
- name: Run delete-branches
id: delete-branches
uses: tagdots/delete-branches@1067f6cf756a462d2da56cffae2df37ea15b600e # 1.2.15
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
repo-url: ${{ github.server_url }}/${{ github.repository }}
max-idle-days: 10
exclude-branches: 'badges'
dry-run: true
Example 2 - Summary (Permanent delete)
| Input | Workflow Spec | Notes |
|---|---|---|
scheduled run |
- cron: '30 17 * * *' |
Run daily at 5:30 pm UTC |
github token permissions |
contents: writepull-requests: read |
Delete requires write permission in contents |
dry-run |
false |
Permanent delete |
exclude-branches |
badges |
Branch badges is found and excluded |
max-idle-days |
10 |
Without new commits longer than 10 days |
Example 2 - Workflow (Permanent delete)
name: delete-github-branches
on:
schedule:
- cron: '30 17 * * *'
permissions:
contents: read
pull-requests: read
jobs:
delete-branches:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: read
- name: Run delete-branches
id: delete-branches
uses: tagdots/delete-branches@1067f6cf756a462d2da56cffae2df37ea15b600e # 1.2.15
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
repo-url: ${{ github.server_url }}/${{ github.repository }}
max-idle-days: 10
exclude-branches: 'badges'
dry-run: false
🖥 Running delete-branches from command line
Prerequisites
* Python (3.12+)
* GitHub fine-grained token (contents: write)
Setup delete-branches
~/work/test $ workon test
(test) ~/work/test $ export GH_TOKEN=github_pat_xxxxxxxxxxxxx
(test) ~/work/test $ pip install -U delete-branches
Example 1 - Run for help
(test) ~/work/test $ delete-branches --help
Usage: delete-branches [OPTIONS]
Options:
--dry-run BOOLEAN default: true
--repo-url TEXT e.g. https://github.com/{owner}/{repo} [required]
--exclude-branches TEXT e.g. 'exclude-branch-1, exclude-branch-2'
--max-idle-days INTEGER Max. no. of idle days (without commits) [required]
--version Show the version and exit.
--help Show this message and exit.
Example 2 - MOCK delete branches without new commits longer than 10 days
| Input | Input Detail | Result |
|---|---|---|
repo-url |
https://github.com/tagdots/test |
process repository tagdots/test |
max-idle-days |
10 |
Without new commits longer than 10 days |
exclude-branches |
test-1, test-2, badges |
Only branch badges is found and excluded |
dry-run |
true |
a. 3 branches exempted from delete: main, badges, pr-branch-01b. 6 branches NOT exempt from deletec. MOCK delete 2 of 6 NOT-exempt-from-delete branches |
(test) ~/work/test $ delete-branches --dry-run true --max-idle-days 10 --exclude-branches "test-1, test-2, badges" --repo-url https://github.com/tagdots/test
🚀 Starting Delete GitHub Branches (dry-run: True, exclude-branches: {'test-1', 'test-2', 'badges'}, max-idle-days: 10)
Current Time (UTC): 2025-08-20 17:08:32
Refined User Exclude Branch(es): {'badges'}
Default Branch : main
Protected Branch : main
Pull Request Head Branch : pr-branch-01
Total Number of Branches : 9
Total Number of Branches (Exempt-From-Delete) : 3
Total Number of Branches (Not-Exempt-From-Delete): 6
From 6 Not-Exempt-From-Delete Branch(es), 2 branch is idle more than 10 day(s)
-------------------------------------------------------------------------------------------------
(MOCK) Delete branch - last update UTC 2025-08-09 13:49:34: branch-test-001
(MOCK) Delete branch - last update UTC 2025-08-08 03:29:34: branch-test-005
Example 3 - Delete branches permanently without new commits longer than 10 days
| Input | Input Detail | Result |
|---|---|---|
repo-url |
https://github.com/tagdots/test |
process repository tagdots/test |
max-idle-days |
10 |
Without new commits longer than 10 days |
exclude-branches |
badges |
Branch badges is found and excluded |
dry-run |
false |
a. 3 branches exempted from delete: main, badges, pr-branch-01b. 6 branches NOT exempt from deletec. Delete 2 of 6 NOT-exempt-from-delete branches permanently |
(test) ~/work/test $ delete-branches --dry-run false --max-days 10 --exclude-branches "badges" --repo-url https://github.com/tagdots/test
🚀 Starting Delete GitHub Branches (dry-run: False, exclude-branches: {'badges'}, max-idle-days: 10)
Current Time (UTC): 2025-08-20 17:26:55
Refined User Exclude Branch(es): {'badges'}
Default Branch : main
Protected Branch : main
Pull Request Head Branch : pr-branch-01
Total Number of Branches : 9
Total Number of Branches (Exempt-From-Delete) : 3
Total Number of Branches (Not-Exempt-From-Delete): 6
From 6 Not-Exempt-From-Delete Branch(es), 2 branch is idle more than 10 day(s)
-------------------------------------------------------------------------------------------------
✅ Delete branch - last update UTC 2025-08-09 13:49:34: branch-test-001
✅ Delete branch - last update UTC 2025-08-08 03:29:34: branch-test-005
🔧 delete-branches command line options
| Input | Description | Default | Required | Notes |
|---|---|---|---|---|
repo-url |
Repository URL | None |
Yes | e.g. https://github.com/{owner}/{repo} |
dry-run |
Dry-Run | True |
No | - |
max-idle-days |
Maximum number of days without new commits | None |
Yes | enter number of days |
exclude-branches |
Branches excluded from deletion | None |
No | comma seperated branches e.g. "branch1, branch2" |
😕 Troubleshooting
Open an issue
🙏 Contributing
For pull requests to be accepted on this project, you should follow PEP8 when creating/updating Python codes.
See Contributing
🙌 Appreciation
If you find this project helpful, please ⭐ star it. Thank you.
📚 References
Metadata
Release files for delete-branches 1.2.17
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| delete_branches-1.2.17.tar.gz | 92.0 kB | Without provenance | Details for delete_branches-1.2.17.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| delete_branches-1.2.17-py3-none-any.whl | Python 3 | none | any | Details for delete_branches-1.2.17-py3-none-any.whl |
Total release size: 100.5 kB
Release files / delete_branches-1.2.17.tar.gz
| Download URL | delete_branches-1.2.17.tar.gz |
|---|---|
| Size | 92.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a78c272e8ee7819d33db76515f89ee1bad97978ab2731b50eab61f4935c1c98f
|
|
BLAKE2b-256 checksum How to use checksums |
c3ee8ad0ffd9f60194204fe95777bd7952c15f314b135d2e2dba11433b772f65
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / delete_branches-1.2.17-py3-none-any.whl
| Download URL | delete_branches-1.2.17-py3-none-any.whl |
|---|---|
| Size | 8.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
62c49f3133068953a04eb64e033e11b9b135bc487d3444df30e68ded0ae7af0f
|
|
BLAKE2b-256 checksum How to use checksums |
3f757659d10b23792728c0e468432901c5b98cb9348a3a55084cfded7ae05b2d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for delete-branches 1.2.17
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.