Edit a GitHub Label with gh label edit

A label called bug needs a new colour, or a rename, without a trip to the web UI, and gh label edit does it from the shell. You will finish with a repeatable command and a read-back check that the change landed in the right repository. The examples use GitHub CLI 2.87.3, the version reported by the installed gh binary, and take about ten minutes.

• You need: an authenticated gh session with permission to edit labels, and either a checkout of the target repository or its explicit OWNER/REPO name.
• What it changes: remote repository metadata.
• Privileges: no sudo. Running as root would not grant GitHub permission.

1. Check the command you are about to use

Read the local help and record the binary version before making a change:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh label edit --help
Update a label on GitHub.

The current label name is the positional argument, and the editable fields are the colour, description and name flags. The colour must be a six-character hexadecimal value.

2. Make the repository target explicit

If a label name exists in more than one repository, leaving out the repository is an easy way to edit the wrong one. Use the inherited --repo option in scripts and in instructions someone else will repeat:

$ gh label edit bug --repo OWNER/REPO --color FF0000

Replace OWNER/REPO with the real repository, and bug with the label's current name. The repository form may include a GitHub Enterprise host, as [HOST/]OWNER/REPO. Quote a label that contains spaces:

$ gh label edit "needs review" --repo OWNER/REPO --description "Waiting for a maintainer review"

3. Change one field first

For a colour-only change, pass a six-character hexadecimal value without a leading hash:

$ gh label edit bug --repo OWNER/REPO --color FF0000

FF0000 is the red value from the manual's example. The CLI flag uses the American spelling, while this guide uses British in prose. Do not pass a leading hash unless you have checked the command version and API path you use. The local contract says six characters, which FF0000 satisfies unambiguously.

A successful edit normally returns to the shell without printing a replacement label record. Treat the exit status as the first checkpoint:

$ printf 'edit exit status: %s\n' "$?"
edit exit status: 0

Run that immediately after gh label edit. If another command ran first, you will print its status instead.

4. Rename and describe a label together

Use the current name as the positional argument and the replacement name in --name:

$ gh label edit bug --repo OWNER/REPO --name big-bug --description "Bigger than normal bug"
$ printf 'edit exit status: %s\n' "$?"
edit exit status: 0

From your side the rename and description update are one remote operation. The old name is the lookup value, so do not repeat it after the command. If the label does not exist, or the account cannot edit it, expect a non-zero status and an error on standard error. Do not retry blindly. Confirm the current label name and repository first.

5. Verify the remote label

Use gh label list to read the label back from the same explicit repository, requesting only the fields you need:

$ gh label list --repo OWNER/REPO --search big-bug \
    --json name,color,description \
    --jq '.[] | select(.name == "big-bug")'
{
  "name": "big-bug",
  "color": "FF0000",
  "description": "Bigger than normal bug"
}

The JSON object is your checkpoint. Confirm the exact name, colour and description, not merely that a search returned something. Searches can include nearby names, and the list command stops at 30 results unless you change the limit. If the query returns nothing, check the repository, spelling and authentication before you edit again.

For a label you did not rename, use its original name in both --search and the jq filter. Keep this verification command in a change record when label state matters to an automated workflow.

6. Recover from a mistake

There is no local undo file for a label edit. Recovery is another edit with the values you want back. If you recorded the old name and description, reverse the rename explicitly:

$ gh label edit big-bug --repo OWNER/REPO \
    --name bug \
    --description "Original description"

Changing a label can affect filters, automation and issue triage without restarting anything. Avoid bulk edits during a release or incident unless the team has agreed them. If Actions or external tooling use the label, check those consumers after the edit.