Managing Github Issue Labels Across Organizations And Repositories

Author: Stu Feeser

GitHub’s default issue labels are really, really bad.

Our GitHub-issue-centric organization suffered under these non-descriptive labels for far too long, so we finally took up the charge for fixing the ‘issue’ once and for all!

In addition to poor defaults, GitHub does not provide the ability to manage issue labels to the degree and fidelity that most users and organizations need. [1] [2] Some things you can’t do with GitHub’s default label management include:

  • Updating default labels for old repos (only new ones)
  • Managing labels across multiple organizations or users
  • Revision control and management of the changes
  • Making backups of existing labels on existing repos

Our solution used the awesome “Labels” Python project in combination with a short Python script that used the “pygithub” library. In the end, we had our old labels backed up and we established a new default issue label scheme that will likely last us for many years to come. Below are the resulting issue labels, the steps we followed, and the script and defaults so you can do the same thing for your repos.

Alta3 Default GitHub Issue Labels Alta3 Default GitHub Issue Labels

Prerequisites

  • User has access to all repositories that will be modified.
  • A GitHub personal access token has been created.
    • Give it a descriptive name.
    • Only select the repo scope.

Install

These steps set up the Python environment and configure it:

python3.8 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip wheel
python -m pip install -r requirements.txt

Example .env file:

GITHUB_USER_TOKEN="<YOUR_TOKEN_HERE>"
LABELS_TOKEN=${GITHUB_USER_TOKEN}
LABELS_USER="<YOUR_USERNAME>"

Run

List All Alta3 Repos

Take a minute to update this script to fetch the lists of users’ and organizations’ repositories that you would like to manage. We will use this list in the next step!

python list-all-repos.py

Make a Backup of All Current Labels

Here we pipe the resulting list to run the labels fetch command on each repoisitory

mkdir -p repo-labels
python list-all-repos.py | xargs -I {} labels fetch --owner alta3 --repo {} --filename repo-labels/{}-labels.toml

Set up a Common Set of Labels for Every Repo

View/edit default-labels.toml for the list of labels. Next, we use the same list of repositories to run the labels sync. This updates each repository to use our new list of issue labels.

python list-all-repos.py | xargs -I {} labels sync --owner alta3 --repo {} --filename all-repos-labels.toml

Now looking at each repository we should see a list of available labels like the image above. In addition to this, we also created a folder full of all the old labels. If we run this script on a regular basis, not only can we keep track of how labels are being created across all of these repos, but we can also take the good ideas and issue labels from one project and expand their use across all the others in our list.

The source code that was used to accomplish this task for Alta3’s repos is available here. Thanks for reading and happy label making!

Next →