Announcing the Stale Repos Action

At GitHub, we believe in the power of collaboration and the importance of maintaining active and thriving projects. As an organization expands and projects evolve, repositories can easily become stale and inactive. It’s important to identify these repositories and take appropriate actions to keep your open source catalog organized and up to date. Archiving projects that are no longer in active development sends an important signal to project communities, influencing a user’s decision to rely on your project.

To address this, we are excited to publish the Stale Repos Action, a tool that helps your organization identify and report on repositories with no activity over a configurable period of time. By using this action, you can easily surface inactive repositories within your GitHub organization, enabling you to make informed decisions about archiving, reviving, or refocusing efforts.

This action was developed by the GitHub Open Source Programs Office (OSPO) so that we can keep our open source projects well maintained. We are launching it as open source in the hopes that it will help you, too! To find out more about how GitHub manages its open source, check out the github-ospo repository.

How does it work?

To start using Stale Repos Action, follow these steps:

1. Create a new repository or use an existing one to host the GitHub Action workflow. This will be the repository where you receive the report as an issue.
2. Configure the required environment values by referencing the sample workflow provided below. The GH_TOKEN and ORGANIZATION values should be replaced with your specific information as repository secrets. If you’re unsure how to create secrets, we have a page of detailed instructions.

   Note: ensure that your GitHub token has read access to all the repositories within the organization you wish to evaluate. GitHub uses a personal access token (classic) with the read:org scope selected.

3. Copy the example workflow into your repository, saving it in the .github/workflows/ directory with the file extension .yml. For instance, you could name it .github/workflows/stale_repos.yml. Note that the sample below has a default value of one year for the length of time something is considered stale. Feel free to configure this to a whole positive number representing the number of days since the last push to the default branch.

name: stale repo identifier

on:
  workflow_dispatch:
  schedule:
    - cron: '3 2 1 * *'

jobs:
  build:
    name: stale repo identifier
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v3

    - name: Run stale_repos tool
      uses: docker://ghcr.io/github/stale_repos:v1
      env:
        GH_TOKEN: ${{ secrets.GH_TOKEN }}
        ORGANIZATION: ${{ secrets.ORGANIZATION }}
        INACTIVE_DAYS: 365

    - name: Create issue
      uses: peter-evans/create-issue-from-file@v4
      with:
        title: Stale repository report
        content-filepath: ./stale_repos.md
        assignees: <YOUR_GITHUB_HANDLE_HERE>

Save and commit the workflow file. The Stale Repos Action will now automatically run based on the schedule you’ve defined, checking for inactive repositories, and generating a report as an issue in the repository where the stale repos workflow is defined.

Understanding the report

Once the Stale Repos Action completes its evaluation, it generates a report in Markdown format. Here’s an example of what you can expect:

The report provides essential information about the inactive repositories, including the repository URL and the number of days it has been inactive. This overview gives you a clear snapshot of the repositories that might require attention.

Support and collaboration

If you have any questions or need assistance with using the Stale Repos Action, we encourage you to open an issue in the GitHub repository. Our community is always ready to lend a helping hand and share their expertise.

Jump in!

For the GitHub OSPO, we will be using this GitHub action to drive conversations with our open source maintainers in order to best curate our open source catalog. We’re excited to see how the Stale Repos Action benefits your organization and contributes to making open source stewardship as an organization a little easier. Take a look and let us know what you think! To see other tools and guides from the GitHub OSPO, check out the github-ospo repository.