manage-stale-branches

This action deletes branches that haven't had a commit in the last stale-duration, and suggest branches which could be deleted due to their inactivity on the last suggested-duration. ⚠️ The branches already merged to the default branch are automatically deleted if the action isn't set for dry-run mode. If you set the dry-run input to true, the action will simply output a preview of what would be done in no dry-run mode.

Table of Contents Using the Action Preview Minimalistic Workflow Sample Workflow Inputs Outputs

Using the Action

In your GitHub workflows, you can reference the action by:

- uses: crazy-matt/manage-stale-branches@v3      # Always use the latest 3.x.x
- uses: crazy-matt/manage-stale-branches@v3.0    # Always use the latest 3.0.x
- uses: crazy-matt/manage-stale-branches@v3.0.1  # Use this specific version

For more information, refer to the GitHub Actions Quickstart.

Preview

Minimalistic Workflow

on:
  push

jobs:
  job1:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: crazy-matt/manage-stale-branches@v3

you don't need to checkout your repository as this action uses the Github API.

Sample Workflow

on:
  schedule:
    - cron: "0 12 * * 1"  # Run every monday at 12 pm

jobs:
  job1:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Manage Stale Branches
        uses: crazy-matt/manage-stale-branches@v3
        with:
          stale-duration: 60d
          suggested-duration: 30d
          dry-run: true
          archive-stale: true
          rate-limit-threshold: 95
          exclude-patterns: |
            release
            ^keep-this.*

Restore your branches with git checkout -b <branch name> archive/<branch name>.

Inputs

name	description	required	default
github-token	GitHub Token with repository write access.	false	${{ github.token }}
stale-duration	Time threshold for stale branches (e.g., "60d", "2w", "1440h"). Accept only a single unit.	false	60d
suggested-duration	Time threshold for suggested branches (e.g., "30d", "1w", "720h"). Accept only a single unit.	false	30d
concurrency	Number of branches to process concurrently.	false	4
dry-run	Run in dry-run mode (no actual deletion).	false	true
archive-stale	Archive instead of deleting stale branches.	false	false
exclude-patterns	Branches to exclude from cleanup. It can be a comma-separated list or a multiline string (yaml list). It can use regex patterns.	false	""
rate-limit-threshold	GitHub API rate limit threshold percentage (0-100). The action will exit gracefully when the rate limit usage reaches this threshold. The action defaults to no threshold (100).	false	100

Outputs

name	description
summary	Summary of deleted/suggested branches.
merged-branches	JSON array string listing the merged branches which have been deleted. Used in dry-run mode, you can pass it easily to a matrix job to handle yourself these branches.
merged-branches-count	Deleted merged branches count.
stale-branches	JSON array string listing the stale branches. Used in dry-run mode, you can pass it easily to a matrix job to handle yourself these branches.
stale-branches-count	Stale branches count.
suggested-branches	JSON array string listing the branches suggested for deletion. Used in dry-run mode, you can pass it easily to a matrix job to handle yourself these branches.
suggested-branches-count	Suggested branches count.