GitHub issue labels
GitHub issue labels are a useful tool for keeping a GitHub project organized. Currently GitHub labels have a name, a color and optionally a description. You can apply labels to issues and also pull-requests and use them as filters when searching.
Creating, editing, and deleting labels is possible using the GitHub website or the GitHub REST API.
Problems with the current workflow
I maintain a number of open source projects on GitHub and even if only a handful see regular activity from contributors, I like to keep things organized for myself. I create new issues to document ideas for new features or areas that need work, for example documentation or making the project more friendly to newcomers.
Every time I start a new project, I find myself copy+pasting a certain set of labels manually from one project to the new one using the web UI. Some labels like for example “bug”, “docs”, “good first issue” exist in almost all of my repositories, regardless of the programming language or the complexity of the project.
Managing GitHub labels across projects is a time-consuming and tedious task. What I would like to have is a tool that allows me to create a batch of labels when starting new projects and manage common issues across different GitHub projects without much manual work.
Typically I use Cookiecutter templates for generating a base directory structure and the initial source code for new projects, which drastically reduces the time until I get to work on what the project is about. It’s technically possible to perform API requests from Cookiecutter via hooks, however this doesn’t help with managing GitHub labels after the initial project generation and across different repositories.
Python 3.6 CLI app to manage GitHub issue labels
I’m happy to announce my new open source project labels! 📝
The idea behind the labels CLI app is to fetch labels for a GitHub repository and write the label information to disk in a easy-to-edit format. I decided to use TOML for this. Then users can open the file in their favorite text editor, modify label parameters and sync them upstream with GitHub and also copy paste label info from other projects.
$ pip install labels
The labels CLI connects to the GitHub API to modify issue labels for a GitHub repository. Please create your own personal API token and choose the correct token scope based on whether you want to manage issue labels for a public or a private repository. Then set up two environment variables in your terminal:
$ export LABELS_USERNAME="<GITHUB_USERNAME>" $ export LABELS_TOKEN="<GITHUB_TOKEN>"
Once you’ve installed labels and set up the environment variables, you’re
ready to use the labels CLI to manage issue labels for a GitHub
repository. The CLI comes with two commands:
Both require you to specify the owner and the name of the GitHub repository using CLI options:
-o, --owner TEXT GitHub owner name -r, --repo TEXT GitHub repository name
When you’re using labels for the first time, you want to fetch
information about the existing labels for your GitHub project. The CLI will
then write a TOML file to your computer with the retrieved
information. The default filename for this file is
labels.toml in your
current working directory and can be changed by passing the
-f, --filename PATH option followed by a path.
$ labels fetch -o hackebrot -r pytest-emoji
[bug] color = "ea707a" description = "Bugs and problems with pytest-emoji" name = "bug" ["code quality"] color = "fcc4db" description = "Tasks related to linting, coding style, type checks" name = "code quality" [dependencies] color = "43a2b7" description = "Tasks related to managing dependencies" name = "dependencies" [docs] color = "2abf88" description = "Tasks to write and update documentation" name = "docs" ["good first issue"] color = "bfdadc" description = "Tasks to pick up by newcomers to the project" name = "good first issue"
Now that you have a file on your computer that represents your GitHub issue labels, you can edit this file and then run labels sync to update the remote repository. But first let’s look into how that works… 🔍
Representation of a GitHub issue label in the written TOML file:
[docs] color = "2abf88" description = "Tasks to write and update documentation" name = "docs"
The section name (
[docs] in the example above) represents the name of the
label for that repository and is identical to the
name field when running
labels fetch. Do not edit the section name of existing labels yourself!
name are parameters that you
can edit with the labels CLI.
name- The name of the label
description- A short description of the label
color- The hexadecimal color code for the label, without the leading
You can make the following changes to issue labels for your repo:
- You can delete a label by removing the corresponding section from the labels file 🗑
- You can edit a label by changing the value for one or more parameters for that label 🎨
- You can create a new label by adding a new section with your desired parameters 📝
When creating labels choose a section name identical to the
Check your label changes before syncing by using the
dryrun CLI option:
-n, --dryrun Do not modify remote labels
$ labels sync -n -o hackebrot -r pytest-emoji
This would delete the following labels: - dependencies This would update the following labels: - bug/ - good first issue This would create the following labels: - duplicate This would NOT modify the following labels: - code quality - docs
labels sync without the
dryrun option also updates the labels
file, so that section names match the
If labels encounters any errors while sending requests to the GitHub API, it will print information about the failure and continue with the next label until it processed all of the labels.
More information & feedback
For more information check out the labels project on GitHub.
If you find it any useful, I’d love to hear from you via twitter! 😃