> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/code-repository/use-harness-code/collaborate-and-develop/labels.md).

# Labels

Labels categorize and filter pull requests in Harness Code Repository. Use them to organize work and make ownership and priority visible in a long pull request list.

Labels support several patterns:

* **Simple categories:** Terms such as `bug`, `feature request`, or `docs`.
* **Priority or severity:** Name and value pairs such as `priority: urgent` or `priority: low`.
* **Ownership:** Labels such as `team: frontend` or `team: backend` that identify who owns the pull request.
* **Filtering:** Any label can narrow a large pull request list.

If you are looking for release tags rather than labels, go to [Tag](/code-repository/use-harness-code/collaborate-and-develop/tag.md).

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* **Label permissions:** You need create and edit permission for Harness Code at the scope where you want the label to exist. Go to the [permissions reference](/harness-ai/use-harness-platform/platform-access-control/permissions-reference.md#code-repository) to review the permission list, and to [RBAC in Harness](/harness-ai/use-harness-platform/platform-access-control.md) to configure roles. If you lack the required permissions, ask your administrator to grant access or to create the label for you.

***

### Types of labels <a href="#types-of-labels" id="types-of-labels"></a>

All labels in Harness Code are customizable, and you can create or modify them to fit your project or team.

A label can be a simple text value such as `Do not Merge`, or it can carry enumerated values such as `status: in progress`, `status: completed`, or `status: blocked`. You can limit a label to a predefined set of values, or allow users to add new values when they apply it.

***

### Create a label <a href="#create-a-label" id="create-a-label"></a>

You can define labels and their values at several scopes. The scope determines where the label is available:

| Scope        | Availability                                      |
| ------------ | ------------------------------------------------- |
| Repository   | That repository only.                             |
| Project      | Every repository in the project.                  |
| Organization | Every project and repository in the organization. |
| Account      | Every repository in the account, for every user.  |

{% hint style="info" %}
Create labels at the highest scope that makes sense, so they stay reusable across projects and repositories.
{% endhint %}

#### Create a repository scoped label <a href="#create-a-repository-scoped-label" id="create-a-repository-scoped-label"></a>

To create a label for a single repository, do the following:

1. Go to **Settings** in the repository.
2. Click **Labels**.
3. Click **+ Create Label**.

#### Create a label at project, organization, or account scope <a href="#create-a-label-at-project-organization-or-account-scope" id="create-a-label-at-project-organization-or-account-scope"></a>

To create a label that spans repositories, do the following:

1. In the Code Repository module, go to **Manage Repositories**.
2. Click **Labels**.
3. Click **+ Create Label**.

#### Add a value to a label <a href="#add-a-value-to-a-label" id="add-a-value-to-a-label"></a>

When you create a label, you can define a list of allowed values that users select from when they apply it. Each value can carry its own color, so `priority: urgent` can render red and `priority: low` can render green.

#### Allow users to add values <a href="#allow-users-to-add-values" id="allow-users-to-add-values"></a>

You can permit users to add new values to an existing label, so a labeling system can evolve with the project. Select the option to allow new values when you create or edit the label.

Every value a user adds joins the label definition and becomes available whenever that label is applied.

***

### Apply a label to a pull request <a href="#apply-a-label-to-a-pull-request" id="apply-a-label-to-a-pull-request"></a>

You apply labels when you create or edit a pull request. Any user with permission to create or review a pull request can add, remove, or update labels and values on it, and every change is recorded in the pull request activity.

* **Simple labels:** Start typing, then select the label.
* **Labels with values:** Find the label, then choose a value. A pull request can carry only one value per label.

Labels appear in the pull request list, so anyone who can view a pull request can see its labels.

#### Add a new value when applying a label <a href="#add-a-new-value-when-applying-a-label" id="add-a-new-value-when-applying-a-label"></a>

If a label allows custom values, select the option to add a new value and enter it in the input field. The new value joins the label definition.

***

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>The + Create Label option is unavailable in Harness Code Repository settings</summary>

Creating a label requires create and edit permission at the scope you are working in. Ask an administrator to assign a role that includes it at the repository, project, organization, or account level.

</details>

<details>

<summary>A label created at organization or account scope does not appear on a Harness Code pull request</summary>

Confirm the pull request repository sits inside the scope where the label was defined. A repository-scoped label is not visible to other repositories.

</details>

<details>

<summary>A user cannot add a new value to an existing label in Harness Code</summary>

The label must be configured to allow users to add values. Edit the label and select the option that permits new values.

</details>

***

### Next steps <a href="#next-steps" id="next-steps"></a>

You can now categorize pull requests consistently and filter a long list down to the work that matters.

* [PR Dashboard](/code-repository/use-harness-code/pull-requests/prs-of-interest.md): Filter pull requests by label across account, organization, and project scope.
* [Create a pull request](/code-repository/use-harness-code/pull-requests/create-pr.md): Apply labels as you open a pull request.
* [Tag](/code-repository/use-harness-code/collaborate-and-develop/tag.md): Use Git tags for releases rather than labels.