Use this Action to cleanup stale / abandoned branches in your GitHub repository
APACHE-2.0 License
Automatically delete abandoned / stale branches from a GitHub repository
This GitHub Action deems a branch as stale or abandoned based on the following criteria:
Branches that meet all these criteria are considered as stale or abandoned and eligible for deletion.
token
: Required - GitHub token for authentication. Use GitHub secrets for security.repository
: Required - The target GitHub repository in the format "owner/repo".ignore-branches
: Optional - Comma-separated list of branches to ignore from deletion.allowed-prefixes
: Optional - Comma-separated list of prefixes a branch must match to be considered for deletion.ignored-prefixes
: Optional - Comma-separated list of prefixes a branch must NOT match to be considered for deletion.last-commit-age-days
: Optional - Number of days since the last commit for a branch to be considered abandoned. Defaults to 30
days.dry-run
: Optional - Perform a dry run without actually deleting branches. Defaults to true
, meaning no branches will be deleted.rate-limit
: Optional - Stop the action if it exceeds 95% of the GitHub API rate limit. Defaults to true
, ensuring the action is halted before hitting the rate limit e.g. exiting with status code 0
instead of failing.This action can be executed independently from workflows within a container. To do so, use the following command:
podman run --rm -it ghcr.io/cbrgm/cleanup-stale-branches-action:v1 --help
name: Cleanup Stale Branches
on:
workflow_dispatch:
schedule:
- cron: '0 0 * * *' # This schedule runs the workflow at midnight every day
jobs:
cleanup-stale-branches:
runs-on: ubuntu-latest
steps:
- name: Cleanup Stale Branches
uses: cbrgm/cleanup-stale-branches-action@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
repository: ${{ github.repository }}
This advanced example includes optional configurations:
name: Cleanup Stale Branches
on:
workflow_dispatch:
schedule:
- cron: '0 0 * * *' # This schedule runs the workflow at midnight every day
jobs:
cleanup-stale-branches:
runs-on: ubuntu-latest
steps:
- name: Cleanup Stale Branches
uses: cbrgm/cleanup-stale-branches-action@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
repository: ${{ github.repository }}
ignore-branches: "foobar,release-*"
ignore-prefixes: "feature/,bugfix/"
last-commit-age-days: 60
dry-run: false
rate-limit: true
In this advanced example:
foobar
and branches starting with release-
.feature/
or bugfix/
are not considered for deletion.60
days are eligible for deletion.dry-run
mode, meaning branches will actually be deleted.rate-limit
check is enabled to prevent exceeding the GitHub API rate limit.sequenceDiagram
participant GitHubAction
participant GitHubAPI
Note over GitHubAction,GitHubAPI: GitHub Action: cleanup-stale-branches-action
GitHubAction->>GitHubAPI: Initialize (Token, Repo Info)
activate GitHubAPI
GitHubAPI-->>GitHubAction: Repository Validated
loop For each Branch in Repository
GitHubAction->>GitHubAPI: Fetch Branch Details
GitHubAPI-->>GitHubAction: Return Branch Details
GitHubAction->>GitHubAction: Evaluate Branch Deletion Criteria
alt Branch Meets Criteria
alt Dry Run Enabled
GitHubAction->>GitHubAction: Log Deletable Branch (No Action)
else Dry Run Disabled
GitHubAction->>GitHubAPI: Delete Branch
GitHubAPI-->>GitHubAction: Branch Deleted
end
else Branch Does Not Meet Criteria
GitHubAction->>GitHubAction: Log Skipping Branch
end
end
deactivate GitHubAPI
You can build this action from source using Go
:
make build
Usage of this action is entirely at your own risk. While this action has been thoroughly tested, there is always the potential for unexpected behavior, especially in different or complex repository setups. I am not responsible for any damage, data loss, or unexpected code deletion that might occur due to misconfiguration or unexpected behavior of this action. Please ensure you have understood the functionality and have correctly configured the action according to your requirements before using it in a production environment.
We welcome and value your contributions to this project! 👍 If you're interested in making improvements or adding features, please refer to our Contributing Guide. This guide provides comprehensive instructions on how to submit changes, set up your development environment, and more.
Please note that this project is developed in my spare time and is available for free 🕒💻. As an open-source initiative, it is governed by the Apache 2.0 License. This license outlines your rights and obligations when using, modifying, and distributing this software.
Your involvement, whether it's through code contributions, suggestions, or feedback, is crucial for the ongoing improvement and success of this project. Together, we can ensure it remains a useful and well-maintained resource for everyone 🌍.