Create a GitHub Label Safely with gh label create

You will finish with a repeatable command for creating a label in a GitHub repository, setting its colour and description, and checking that the result is present. The examples use GitHub CLI 2.87.3, installed here as the gh package command. GitHub CLI talks to the remote service, so authentication and repository permissions matter.

Allow about ten minutes. You need GitHub CLI, an authenticated account that can manage labels in the target repository, and the repository's OWNER/REPO name. No root access is needed. This guide changes repository metadata, so read the name and colour carefully before running the create command.

1. Check the installed command

Start with read-only checks. They confirm which binary is on your path and show the option syntax supplied by the installed version:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh label create --help
Create a new label on GitHub, or update an existing one with \`--force\`.

The command shape is gh label create NAME [flags]. The local manual describes --description, the short -c colour option, --force and the inherited --repo option. The exact help output may contain more surrounding text, but those are the options this workflow uses.

Checkpoint: if gh --version fails, stop here and fix the installation or PATH. Do not substitute a similarly named script without checking it first.

2. Confirm the repository and authentication

Use the repository in the command rather than relying on the current directory. This is especially useful when you are working outside a checkout or have several repositories open:

$ REPO='OWNER/REPO'
$ gh auth status
$ gh label list --repo "$REPO" --limit 30

Replace OWNER/REPO with the real repository, such as acme/widgets. Do not leave the placeholder in a command that changes state. The list command is a useful sanity check: it proves that the selected repository is reachable and shows existing label names. If authentication fails, resolve that with your normal GitHub CLI login process before continuing.

The inherited --repo flag also accepts [HOST/]OWNER/REPO for a GitHub Enterprise host. Use the host explicitly when the repository is not on github.com. Elevated privileges do not fix a wrong host, missing permission or expired GitHub token.

3. Choose a label name, description and colour

A label name is required. Description and colour are optional, but setting both makes the result easier to recognise and less dependent on GitHub's defaults. The installed manual requires the colour to be a six-character hexadecimal value. Use six digits without a leading #, for example E99695:

$ LABEL='needs-reproduction'
$ DESCRIPTION='The issue needs a minimal reproducible example'
$ COLOUR='E99695'

Names and descriptions are repository metadata, so avoid putting secrets, email addresses or incident details into them. Keep the values quoted as shown. Quoting protects spaces and shell metacharacters from being interpreted by your shell; it does not validate the content for GitHub.

Do not assume a missing colour means a stable default. The local manual says that GitHub CLI chooses a random colour when the colour option is omitted. If the appearance matters, provide the six-character value explicitly. A malformed value is likely to be rejected by the command or the service; fix it rather than trying repeated guesses.

4. Create the new label

Run this ordinary user command only after checking the repository and values:

$ gh label create "$LABEL" \
    --description "$DESCRIPTION" \
    -c "$COLOUR" \
    --repo "$REPO"

A successful invocation creates the label in the selected repository. The command does not require sudo. Its network request can fail because of authentication, permissions, repository spelling or connectivity, so check the error before rerunning it.

Checkpoint: verify the label by searching its name and asking for JSON fields that make the result unambiguous:

$ gh label list --repo "$REPO" --search "$LABEL" --json name,description,color
[{"color":"E99695","description":"The issue needs a minimal reproducible example","name":"needs-reproduction"}]

The JSON is an example of the fields to inspect, not a promise about whitespace or array formatting. Confirm the name, description and colour. If the search returns several similar labels, use the exact name in the returned records.

5. Handle an existing label deliberately

If the name already exists, do not add --force by reflex. The manual defines --force as updating the existing label's colour and description. That is a state change, and it can overwrite metadata another maintainer chose:

$ gh label create "$LABEL" \
    --description "$DESCRIPTION" \
    -c "$COLOUR" \
    --force \
    --repo "$REPO"

Use this only after comparing the current record with the values you intend to apply. There is no separate confirmation prompt in the documented command shape. Treat --force as an explicit overwrite instruction, not as a harmless retry switch.

Recovery is straightforward if you know the previous description and colour: run the same command with the original values and --force. If you do not know them, stop and ask a repository maintainer or inspect the repository's label history through your normal GitHub workflow. Creating a duplicate-looking label with a different spelling is usually worse than resolving the existing one.

6. Diagnose the common failures

A missing required name is a local command error. A repository error usually means that REPO is wrong, the host is wrong, or your account cannot manage labels there. Recheck without changing anything:

$ printf 'repository: %s\n' "$REPO"
$ gh label list --repo "$REPO" --limit 1
$ gh auth status

If the colour is rejected, count the hexadecimal characters and remove any # prefix. The documented requirement is exactly six characters. If a label appears to be missing after a successful command, search with the exact name and the same --repo value used for creation. Looking at the current checkout's repository is not a substitute for specifying the target explicitly.

Do not run the create command repeatedly while investigating a network timeout. First list the labels, then decide whether a retry is safe. With --force, a retry can also reapply an update, so record the intended values and compare them with the current result.