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