Skip to content
You're viewing an older version of this GitHub Action. Do you want to see the latest version instead?
delete

GitHub Action

Stale Branches

v5.0.0

Stale Branches

delete

Stale Branches

Finds and deletes stale branches

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: Stale Branches

              
  uses: crs-k/[email protected]
Learn more about this action in crs-k/stale-branches

Choose a version

ci status ci status

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.
    image
  • 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

image

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/[email protected]

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/[email protected]
      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.