Stale Branches

Finds and deletes stale branches. By default it aligns with this definition, but can be configured for other use cases.

When a branch has been inactive for more than the days-before-stale input, it is considered stale. The branch will be deleted once it has been inactive longer than days-before-delete.

By default, a stale branch is defined as a branch that:
- has had no commits in the last 120 days.
- has no protection rules.
- is not the default branch of the repository.
- See inputs for more info.
See example workflow.

Usage

Pre-requisites

Create a workflow .yml file in your repository's .github/workflows directory. An example workflow is available below. For more information, reference the GitHub Help Documentation for Creating a workflow file.

Inputs

Inputs are defined in action.yml. None are required.:

Name	Description	Default
`repo-token`	Token used to authenticate with GitHub's API. Can be passed in using `${{ secrets.GITHUB_TOKEN }}`.	`${{ github.token }}`
`days-before-stale`	Number of days a branch has been inactive before it is considered stale.	120 days
`days-before-delete`	Number of days a branch has been inactive before it is deleted.	180 days
`comment-updates`	A comment with updated information will be added to existing issues each workflow run.	false
`max-issues`	This dictates the number of `stale branch 🗑️` issues that can exist. Also, the max number of branches that can be deleted per run.	20
`tag-committer`	When an issue is opened, the last committer will be tagged in the comments.	false
`stale-branch-label`	Label to be applied to issues created for stale branches. *As of v2, this must* be unique to this workflow**.	`stale branch 🗑️`
`compare-branches`	This compares each branch to the repo's default branch. When set to `info`, additional output describes if the current branch is ahead, behind, diverged, or identical to the default branch. When set to `save`, this prevents branches from being deleted if they are ahead of or diverged from the default branch. When set to `off`, no additional calls are made.	off
`branches-filter-regex`	An optional Regex that will be used to filter branches from this action.	''
`rate-limit`	If this is enabled, the action will stop if it exceeds 95% of the GitHub API rate limit.	true
`pr-check`	If this is enabled, the action will first check for incoming/outgoing PRs associated with the branch. If a branch has an active pr, it will not be ignored.	false

Outputs

Outputs are defined in action.yml:

Name	Description
`stale-branches`	List of all branches identified as stale during a workflow run.
`deleted-branches`	List of all branches deleted during a workflow run.

Terminal Output Groups

Output is grouped by branch.
- Active branches are green
- Stale branches are yellow
- Dead branches are red
- Skipped branches are blue

Example workflow

With defaults

# .github/workflows/stale-branches.yml

name: Stale Branches

on:
  schedule:
    - cron: '0 6 * * 1-5'
    
permissions:
  issues: write
  contents: write

jobs:
  stale_branches:
    runs-on: ubuntu-latest
    steps:
    - name: Stale Branches
      uses: crs-k/stale-branches@v5.0.0

With Inputs

# .github/workflows/stale-branches.yml

name: Stale Branches

on:
  schedule:
    - cron: '0 6 * * 1-5'
    
permissions:
  issues: write
  contents: write

jobs:
  stale_branches:
    runs-on: ubuntu-latest
    steps:
    - name: Stale Branches
      uses: crs-k/stale-branches@v5.0.0
      with:
        repo-token: '${{ secrets.GITHUB_TOKEN }}'
        days-before-stale: 120
        days-before-delete: 180
        comment-updates: false
        max-issues: 20
        tag-committer: false
        stale-branch-label: 'stale branch 🗑️'
        compare-branches: 'info'
        branches-filter-regex: '^((?!dependabot))'
        rate-limit: false
        pr-check: false

Contributing

Contributions are welcomed. Please read the contributing.