| 1 | --- |
| 2 | title: Labels |
| 3 | description: Say what an issue or pull request is with colored labels, filter lists by them, and manage a repository's labels. |
| 4 | --- |
| 5 | |
| 6 | A label says what an issue or a pull request is: a `bug`, a `question`, |
| 7 | `good first issue`. Each repository has its own labels, each with a name, |
| 8 | a color and a description. Issues and pull requests carry them by name, |
| 9 | lists show them as colored chips, and you can filter either list by one. |
| 10 | |
| 11 | ## The labels a repository starts with |
| 12 | |
| 13 | A new repository starts with these: |
| 14 | |
| 15 | | Label | Color | Description | |
| 16 | | --- | --- | --- | |
| 17 | | `bug` | `d73a4a` | Something isn't working | |
| 18 | | `documentation` | `0075ca` | Improvements or additions to documentation | |
| 19 | | `duplicate` | `cfd3d7` | This issue or pull request already exists | |
| 20 | | `enhancement` | `a2eeef` | New feature or request | |
| 21 | | `good first issue` | `7057ff` | Good for newcomers | |
| 22 | | `help wanted` | `008672` | Extra attention is needed | |
| 23 | | `invalid` | `e4e669` | This doesn't seem right | |
| 24 | | `question` | `d876e3` | Further information is requested | |
| 25 | | `wontfix` | `ffffff` | This will not be worked on | |
| 26 | | `dependencies` | `0366d6` | Updates a dependency | |
| 27 | | `security` | `ee0701` | A security fix or a vulnerability | |
| 28 | |
| 29 | A repository made before labels had colors kept every label its issues |
| 30 | already carried. To give it the defaults too: |
| 31 | |
| 32 | 1. Open the project's **Issues**, then **Labels**. |
| 33 | 2. Choose **Add the default labels**. |
| 34 | |
| 35 | Labels the repository has already are left as they are. |
| 36 | |
| 37 | ## Put labels on an issue or a pull request |
| 38 | |
| 39 | 1. Open the issue or pull request. |
| 40 | 2. In the sidebar, choose the settings icon beside **Labels**. |
| 41 | 3. Tick labels on and off. Type to find one by its name or description. |
| 42 | 4. Close the menu. The labels save as it closes. |
| 43 | |
| 44 | Each label put on or taken off is noted in the conversation, and is an |
| 45 | `issue.labeled` or `issue.unlabeled` event (`pull.labeled` and |
| 46 | `pull.unlabeled` on a pull request). |
| 47 | |
| 48 | Who may do this: |
| 49 | |
| 50 | - The author of an issue or a pull request, and whoever asked g1t for one, |
| 51 | may use the repository's labels on it. |
| 52 | - Anyone with the Triage [role](/guides/access-and-roles/) or higher may |
| 53 | label anything, and make a label as they go: type a name the repository |
| 54 | does not have, and choose **Create**. |
| 55 | |
| 56 | An issue or a pull request carries at most 20 labels. |
| 57 | |
| 58 | You can label an issue as you open it, too: tick labels on **New issue**, |
| 59 | or with the Write role, type new ones beside them. |
| 60 | |
| 61 | ## Filter by a label |
| 62 | |
| 63 | On **Issues** or **Pull requests**, choose **Label** and pick one. The |
| 64 | address keeps it, as `?label=bug`, so the filtered list can be shared. You |
| 65 | can also write it as `?q=label:bug`, with quotes around a name with |
| 66 | spaces: `?q=label:"good first issue"`. **Clear filters** shows everything |
| 67 | again. |
| 68 | |
| 69 | ## Manage a repository's labels |
| 70 | |
| 71 | Open **Issues**, then **Labels**, at `g1t.sh/<owner>/<repo>/labels`. It |
| 72 | lists every label with its description and how many issues and pull |
| 73 | requests carry it; choose a count to see them. Search finds a label by its |
| 74 | name or description. |
| 75 | |
| 76 | With the Write role or higher you can (applying labels needs only Triage): |
| 77 | |
| 78 | | To | Do this | |
| 79 | | --- | --- | |
| 80 | | Make a label | **New label**: a name (lowercase, at most 50 characters), a description (at most 100), and a color. | |
| 81 | | Change one | **Edit**. Renaming a label renames it on every issue and pull request that carries it. | |
| 82 | | Delete one | **Delete**. It comes off everything that carries it. This cannot be undone. | |
| 83 | |
| 84 | Names are lowercase and unique in a repository: `Bug` and `bug` are the |
| 85 | same label. |
| 86 | |
| 87 | ## Labels and g1t |
| 88 | |
| 89 | - An [agent rule](/guides/working-with-g1t/) can queue an issue for g1t |
| 90 | when it is given a label. |
| 91 | - [Dependency updates](/guides/dependency-updates/) carry `dependencies` |
| 92 | and their ecosystem's label (`javascript`, `rust`, `go`, `python`, …) |
| 93 | unless `labels` in the file says otherwise. Labels the repository lacks |
| 94 | are made for them. |
| 95 | - [Workflows](/guides/actions/) can start on `labeled` and `unlabeled` |
| 96 | activity of `issues` and `pull_request`. |
| 97 | |
| 98 | ## From the API |
| 99 | |
| 100 | | To | REST | MCP | |
| 101 | | --- | --- | --- | |
| 102 | | List labels | `GET /repos/{owner}/{name}/labels` | `repository` `list_labels` | |
| 103 | | Make one | `POST /repos/{owner}/{name}/labels` | `repository` `create_label` | |
| 104 | | Change one | `PATCH /repos/{owner}/{name}/labels/{label}` | `repository` `update_label` | |
| 105 | | Delete one | `DELETE /repos/{owner}/{name}/labels/{label}` | `repository` `delete_label` | |
| 106 | | Add the defaults | `POST /repos/{owner}/{name}/labels/defaults` | `repository` `add_default_labels` | |
| 107 | | An item's labels | `GET /repos/{owner}/{name}/issues/{number}/labels` | `issue` `labels` | |
| 108 | | Add labels | `POST /repos/{owner}/{name}/issues/{number}/labels` | `issue` `add_labels` | |
| 109 | | Replace them | `PUT /repos/{owner}/{name}/issues/{number}/labels` | `issue` `set_labels` | |
| 110 | | Take one off | `DELETE /repos/{owner}/{name}/issues/{number}/labels/{label}` | `issue` `remove_labels` | |
| 111 | | Take all off | `DELETE /repos/{owner}/{name}/issues/{number}/labels` | `issue` `remove_labels` | |
| 112 | |
| 113 | The `issues/{number}/labels` routes work on pull requests too, since issues |
| 114 | and pull requests share numbers. URL-encode a label's spaces in a path: |
| 115 | `good%20first%20issue`. |
| 116 | |
| 117 | ```sh |
| 118 | curl -X POST https://api.g1t.sh/repos/acme/web/issues/12/labels \ |
| 119 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 120 | -H "Content-Type: application/json" \ |
| 121 | -d '{"labels": ["bug", "help wanted"]}' |
| 122 | ``` |
| 123 | |
| 124 | `labels` on `create_issue`, `update_issue` and `update_pull_request` set |
| 125 | them as well, and `label` filters `list_issues` and `list_pull_requests`. |
| 126 | Managing labels needs a token with `issues:write`. |