# Manage labels

Create, rename, recolour and delete a repository's labels, shared by its issues and pull requests.

**Issues → Labels** lists the repository's labels with the number of open issues on each. The
examples use the repository id `5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60`; replace needs-review
with the label's name.

**Important:**
Deleting a label takes it off every issue and pull request. The issues stay.

## Prerequisites

- `git:ListIssues` on the repository to see the labels, and `git:ManageLabels` to create, change or
  delete one. Setting a pull request's labels needs `git:UpdateIssue`.
- In the Deutsche Cloud Console, also `git:GetRepository` to open the repository's pages (without it the page
  is not found).
- In the Deutsche Cloud Console, labels of an archived repository cannot be changed: **New label** is not
  shown.

## Create a label

A name is 1 to 50 characters and unique in the repository; a description is
at most 200 characters. A colour is six hex digits.

**Console**
1. In the repository, choose **Issues**, then **Labels**.
2. Choose **New label**.
3. For **Name**, enter needs-review. Optionally enter a **Description**.
4. For **Colour**, choose a swatch or enter six hex digits. The default is `d73a4a`.
5. Choose **Create label**. The label is listed.

**CLI**
```sh
dcloud git labels create 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  --name needs-review --color d73a4a
```

Without `--color` the label is grey (`6b7280`).

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/labels
{ "name": "needs-review", "color": "d73a4a" }
```

Without `color` the label is grey (`6b7280`).

A name the repository already has is refused with 409 `A label "needs-review" exists already`.

## Change or delete a label

In the Deutsche Cloud Console, choose the label in the list (or **Edit** in its actions menu). Change the
name, description or colour and choose **Save**; a rename shows on every issue and pull request
that carries the label. To delete it, choose **Delete label** in the same dialog and confirm.

With the CLI or API, use `dcloud git labels update` and `dcloud git labels delete`. An update to a name
another label already has answers 404 `Not found or name taken`.

## Label a pull request

In the pull request's sidebar, choose labels under **Labels**. `PUT …/pulls/{n}/labels`
(`dcloud git labels set-pull-request-labels`) replaces a pull request's labels; it takes at most 20
names, and a name the repository does not have is refused with 422 `No such label: <name>`. Each
label added or removed starts the `labeled` or `unlabeled` pull request event for workflows, and a
workflow reads them as `github.event.pull_request.labels`, for example
`contains(github.event.pull_request.labels.*.name, 'needs-review')`.

## Related

- [Open an issue](open-an-issue.md)
- `git.labels.create` · `dcloud git labels create`
