How to Create and Add Labels to GitHub Pull Requests & Issues

GitHub labels are a useful way to categorize and organize issues and pull requests in your repositories. If you want to standardize your labeling approach across teams or across repositories, you will need to document your strategy and enable developers with automated processes and guidelines.

In this guide, we’ll outline common ways that teams use labels, and how to create and apply them to your pull requests in a standard way.  

The Role of GitHub Labels

Every new repository comes with a set of default labels for some of the most common uses, like “bug”, “help needed”. or “question”. You can see a full list of the default labels here.

Beyond these default labels, you can create custom labels and utilize them to organize your repository. Every organization has different needs, so let’s look at an example. 

You can see how Hashicorp uses labels on their popular Nomad project. 

Nomad is a flexible workload orchestrator that can deploy a mix of microservice, batch, containerized, and non-containerized applications. In the Nomad repository, they have the default labels, but they also have categories of labels like “backport/…”, “theme/…”, “...stage/”, and “type/”.

Here are some of the custom labels in the “stage” category:

• stage/waiting-reply
• stage/thinking
• stage/not-a-bug
• stage/needs-verification
• stage/needs-investigation
• stage/needs-discussion
• stage/duplicate
• stage/accepted

The “theme” category is used as a way of classifying what the pull request is related to (e.g. “auth”, “api”, “autoscaling”, “bad-ux”).

Since Nomad is an open source project, labels are especially helpful in coordinating efforts. In your organization, depending on the level of collaboration, labels can also play an important role in creating standard workflows and improving communication.

Creating New Labels in GitHub

There are a few ways to create new labels. You can choose whichever method you are most comfortable with, and they will all do the job.

Using the GitHub Console:

The process for creating labels in the Console is pretty simple. The following screenshots are from GitHub documentation.

1. Navigate to the repository you want to create labels for and select either Issues or Pull Requests.

2. You’ll now see a Labels tab above the list:

3. You’ll see a New Label option to the right of the search. Click it and add a Name and Description.

4. You can also customize the label color using a hexacode or by selecting one of the default color options available here:

5. Click Create Label to save your new label and make it available to other team members.

You can also create Default labels, which are included in any new repository created by your organization. You can create Default labels by navigating to Your Organizations after clicking on your profile photo in the top right corner. Click Settings, then select Repository under the Code, planning, and automation section of the sidebar. Click Repository defaults and Repository labels. You’ll see a New Label button which leads to the same create label workflow we outlined above.

Using the GitHub CLI:

If you want to use the GitHub CLI to create labels instead, you can do that by running the following command:

gh label create <name>

Similar to the Console steps, you can define your new label by using the following options:

• Color: use -c or --color <string>
• Description: use -d or --description <string>
• Target repository: use -R or --repo <[HOST/]OWNER/REPO>
• Update an existing label with new characteristics: use -f or --force

Here’s an example command:

gh label create “need help” 
--description "I need a reviewer to help resolve a problem" 
--color f15a3a

You can verify that your label was successfully created by running a list command:

gh label list --search “need help” 

If your new label is returned, then you know you have created it successfully.

Using the Labels API:

Lastly, you can also create labels by using GitHub’s Labels API.

You can make a POST request, using an Accept parameter set to application/vnd.github+json. For your path parameters, you need to specify the owner and repo. In the body parameters, you need to specify the name, color, and description for your label. Here’s an example:

curl \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://api.github.com/repos/OWNER/REPO/labels \
  -d '{"name":"need help","description":"I need a reviewer to help resolve a problem","color":"f15a3a"}'

If your POST request is successful, you’ll get a Status: 201 response and this output.

{  
  "id": 319127163,  
  "node_id": "EWY2TGFuZBwyMCsrMER5NPQ=",  
  "url": "https://api.github.com/repos/OWNER/REPO/labels/bug",  
  "name": "need help",  
  "description": "I need a reviewer to help resolve a problem",
  "color": "f15a3a",  
  "default": true
}

Now that you have created a new label, let’s look at applying it to a pull request or issue.

Adding Labels to Pull Requests and Issues in GitHub

Now that you have your custom label created, you will need to apply it. Let’s use the example of adding a label to a pull request.

Blink Automation: Add Label to GitHub Pull Requests with Matching Conditions

Blink + GitHub

Try This Automation

Using the GitHub Console:

To add a label, all you need to do is navigate to the specific issue or pull request that you want to label. Next to “Labels” in the right sidebar, click the Gear icon and select the label you want to apply.

Using the GitHub CLI:

You can run an edit command with the GitHub CLI to add labels to your pull request or your issue.

For adding a label to a pull request, use this command:

gh pr edit [<number> | <url> | <branch>] --add-label <name>

If you don’t specify the branch, it will default to the pull request associated with the current branch. Here’s an example of this command:

gh pr edit 65 --add-label "bug,need help" --add-reviewer <team-member-a>

For adding a label to an issue, use this command:

gh issue edit {<number> | <url>} [flags]

Here’s an example of this command:

gh issue edit 82 --add-label "resolved" --remove-label "need help"

Using the Labels API:

Similar to creating new labels, you can use GitHub’s Labels API to apply labels to pull requests.

You can make a POST request, using an Accept parameter set to application/vnd.github+json. For your path parameters, you need to specify the owner, the repo, and the issue number. In the body parameters, you need to specify the label you want to apply. Here’s an example:

curl \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER/labels \
  -d '{"labels":["need help"]}'

Here’s an example response:

[
  {
    "id": 319127163,
    "node_id": "EWY2TGFuZBwyMCsrMER5NPQ=",
    "url": "https://api.github.com/repos/OWNER/REPO/labels/need%20help",
    "name": "need help",
    "description": "I need a reviewer to help resolve a problem",
    "color": "f15a3a",
    "default": true  
  },
]

If your POST request is successful, you’ll get a Status: 200 response.

Automating Labeling with Blink

We’ve just covered all of the manual ways to create labels and apply them to issues and pull requests in your GitHub account. This manual approach works well if you are using one repository and you have a small team. You can encourage labeling by simply sharing your organization’s guidelines.

If you have multiple teams, multiple repositories, or you are growing quickly, you may need to implement some automation to ensure that your labeling practices are being executed in a uniform way.

With Blink, you can use automations like this one to apply labels based on triggers or parameters so you achieve an organized repository.

You can import this automation from the Blink library into your account and customize it based on your organization’s needs. For example, you can drag-and-drop new actions into the canvas or set up conditional subflows.

Get started with Blink and see how easy it can be to apply labels automatically.