Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.
| Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar | 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**, | |
| Merge main (membership, two-factor, GitHub repo roles) into tokens | 59 | or with the Write role, type new ones beside them. |
| Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar | 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 | ||
| Merge main (membership, two-factor, GitHub repo roles) into tokens | 76 | With the Write role or higher you can (applying labels needs only Triage): |
| Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar | 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`. |
This file's history is long; its oldest lines are credited to the oldest commit read.