Edit a GitHub Label Safely with gh label edit

You will finish with a repeatable command for changing a GitHub label's name, colour or description, plus a read-back check that confirms the change landed in the repository you intended. The examples use GitHub CLI 2.87.3, which is the version reported by the installed gh binary.

Allow 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. This guide changes remote repository metadata. It does not need sudo, and running it 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 command takes the current label name as its positional argument. The editable fields are the colour, description and name flags. The colour value must be a six-character hexadecimal value. The installed package database may report a different distribution package revision from the binary, so use gh --version when documenting the behaviour of the executable you actually ran.

Checkpoint: make sure the help shows gh label edit <name> [flags]. If the command is missing or the flags differ, stop and check which gh binary is first in your PATH.

2. Make the repository target explicit

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

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

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

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

These commands send a remote update. Before pressing Enter, read back the repository and every value in the command. A typo in a label name is safer than a vague target, but an unexpected label with the same name in another repository is not.

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 used in the manual's example. GitHub CLI names the colour flag with the American spelling, while this guide uses the British spelling in prose. Do not pass a leading hash unless you have checked the command version and API path you are using; the local contract says six characters, which is unambiguously satisfied by FF0000.

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, its status is what you will print 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

The rename and description update are one remote operation from your point of view. The old name is the lookup value, not the value to repeat 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: first confirm the current label name and repository.

Descriptions and names are ordinary shell arguments. Double quotes preserve spaces, while single quotes are useful when the text contains shell characters that should remain literal. Do not build the command by concatenating untrusted label text into an eval expression.

5. Verify the remote label

Use gh label list to read the label back from the same explicit repository. Request only the fields needed for the check:

$ 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 the useful checkpoint. Confirm the exact name, colour and description, not merely that a search returned a result. Search results can include nearby names, and the list command has a default limit of 30 unless you change it. If the query returns nothing, check the repository, spelling and authentication before making another edit.

For a label that was not renamed, substitute 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 using the values you want restored. 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"

Do not guess the old description. Ask a repository administrator or inspect a trusted record before restoring it. If only the colour was wrong, pass the intended six-character value with the colour flag. A failed command may have made no change, so verify the current state before attempting recovery.

Changing a label can affect filters, automation and issue triage without restarting a service. Avoid bulk edits during a release or incident unless the team has agreed the change. If the label is used by Actions or external tooling, verify those consumers after the edit.