| 1 | --- |
| 2 | title: Work items |
| 3 | description: Track any work, a feature, a bug or a chore, as a work item of your workspace. Link it to the repositories it starts in and lands in, number it once for the whole workspace, close it when every repository has landed, and work on it from the site, the CLI, MCP and the API. |
| 4 | --- |
| 5 | |
| 6 | A work item is anything your team means to do: a feature, a bug, a chore. |
| 7 | It belongs to the workspace, not to one repository, so work that spans a |
| 8 | service, its client and its docs is one item, with one number, one |
| 9 | conversation and one place that says what is done. |
| 10 | |
| 11 | **Work** is in the left rail, directly after **Home**, at |
| 12 | `g1t.sh/<workspace>/-/work`. A work item's page is |
| 13 | `g1t.sh/<workspace>/-/work/<number>`. |
| 14 | |
| 15 | Work items used to be issues, one repository's each. [Issues became work |
| 16 | items](/about/issues-became-work-items/) says what changed for the ones you |
| 17 | had. |
| 18 | |
| 19 | ## What a work item has |
| 20 | |
| 21 | - a **title** and a **description** in Markdown. Whoever works on it, |
| 22 | person or agent, works from this text. Say what done means in plain |
| 23 | words, under a `## Definition of done` heading if you like: it is |
| 24 | context for whoever works on it and its reviewers, not something a merge |
| 25 | waits on; |
| 26 | - its **repositories**, each with a role (see below); |
| 27 | - **labels** and a **milestone**, both the workspace's; |
| 28 | - **comments**, **reactions** and **assignees**; |
| 29 | - what it is **blocked by**: other work items that must land first; |
| 30 | - a **state**: open or closed. A closed work item records why: |
| 31 | `completed` or `not_planned`. |
| 32 | |
| 33 | ## One number for the workspace |
| 34 | |
| 35 | Work items and pull requests share one sequence of numbers per workspace, |
| 36 | so `#12` names exactly one thing in it. Pull requests still live in their |
| 37 | repository, at `g1t.sh/<owner>/<repo>/pull/<number>`, but a new one takes |
| 38 | the workspace's next number. Pull requests opened before work items keep |
| 39 | the numbers they had. |
| 40 | |
| 41 | Wherever Markdown shows, in a description, a comment, a commit message or |
| 42 | chat, a reference links to what it names: |
| 43 | |
| 44 | | You write | It names | |
| 45 | | --- | --- | |
| 46 | | `#12`, in a repository | That repository's pull request #12, else the work item that was its issue #12, else the workspace's work item #12, else pull request #12 in another of the workspace's repositories | |
| 47 | | `#12`, outside a repository | The workspace's work item #12, else its pull request #12 | |
| 48 | | `owner/name#12` | `#12` as it reads in repository `owner/name` | |
| 49 | | `workspace#12` | Work item or pull request #12 of another workspace | |
| 50 | |
| 51 | So old references keep working: `#12` written about an issue before work |
| 52 | items, `owner/repo#12`, and `Closes #12` in a commit, all reach the work |
| 53 | item that issue became. |
| 54 | |
| 55 | ## Repositories and their roles |
| 56 | |
| 57 | A work item links any number of the workspace's repositories, each in one |
| 58 | role: |
| 59 | |
| 60 | | Role | Means | |
| 61 | | --- | --- | |
| 62 | | `origin` | The repository it was filed in. A work item opened from a repository has one; one opened on **Work** itself has none. | |
| 63 | | `target` | A repository the work is meant to land in. | |
| 64 | | `touched` | A repository where a pull request or commit for it landed or is in progress. g1t adds these itself, when a pull request is opened for the work item or a commit names it. | |
| 65 | |
| 66 | A work item's page lists its repositories with their roles, each with its |
| 67 | pull requests for the item and whether it has **landed**. Under them, |
| 68 | **Suggested** names repositories it may also need, each with why: work |
| 69 | items like it landed there before, its CODEOWNERS cover what the item |
| 70 | talks about, or sessions on the item touched it. Choose **Add as target** |
| 71 | to link one. |
| 72 | |
| 73 | With the Triage role or higher, choose **Link a repository** to add one |
| 74 | in a role, and the cross beside a repository to unlink it. Each is noted in |
| 75 | the conversation, and is a `work_item.linked` or `work_item.unlinked` |
| 76 | event. |
| 77 | |
| 78 | ## Closing a work item |
| 79 | |
| 80 | A pull request that merges into its repository's default branch, or a |
| 81 | commit pushed there, marks **its repository** as landed on every work item |
| 82 | it names after a closing keyword (`Closes #12`, `Fixes #12`, |
| 83 | `Resolves #12`; see [Closing work items](/guides/pull-requests/#closing-work-items)). |
| 84 | The work item records it as a **resolution**: the repository, and the pull |
| 85 | request or commit that landed it. |
| 86 | |
| 87 | The work item closes as `completed`: |
| 88 | |
| 89 | - when it has no target, at the first resolution; |
| 90 | - when it has targets, once every target has landed. |
| 91 | |
| 92 | Until then it stays open, and its page says which targets are still |
| 93 | missing. A pull request that does only part of a repository's share says |
| 94 | `Part of #12` instead (or `Refs #12`): it links the pull request to the |
| 95 | work item, and the repository as touched, without landing anything. |
| 96 | |
| 97 | A work item in another workspace is never closed by your repositories: |
| 98 | `Closes other-workspace#3` does nothing. |
| 99 | |
| 100 | You can also close a work item yourself, as `completed` or `not_planned`, |
| 101 | and reopen it. Reopening clears its resolutions. |
| 102 | |
| 103 | ## Labels and milestones |
| 104 | |
| 105 | Labels and milestones belong to the workspace, and every work item and |
| 106 | pull request in it uses the same ones. See [labels](/guides/labels/) and |
| 107 | [milestones](/guides/milestones/). Both are under **Work**: |
| 108 | **Labels** at `g1t.sh/<workspace>/-/work/labels` and **Milestones** at |
| 109 | `g1t.sh/<workspace>/-/work/milestones`. |
| 110 | |
| 111 | ## Who sees a work item |
| 112 | |
| 113 | - The workspace's members see every work item. |
| 114 | - Anyone who can read a work item's origin repository sees it. Work items |
| 115 | filed in a public repository are public, and anyone who can take part in |
| 116 | a public repository can file one there. |
| 117 | - A work item with no origin is seen only by members. |
| 118 | |
| 119 | What you can do with one follows your [role](/guides/access-and-roles/): |
| 120 | the higher of your role in the workspace and your role in its origin |
| 121 | repository. Triage labels, assigns and links repositories; the author and |
| 122 | whoever asked for it can edit it. |
| 123 | |
| 124 | ## The Work list |
| 125 | |
| 126 | **Work** lists the workspace's work items, open first, newest first. |
| 127 | Filter it by state, label, milestone, assignee, repository and role (for |
| 128 | example the items a repository is a target of). The address keeps the |
| 129 | filters, so a filtered list can be shared. |
| 130 | |
| 131 | A repository's **Work** tab is the same list, filtered to the work items |
| 132 | linked to that repository: `g1t.sh/<workspace>/-/work?repo=<name>`. |
| 133 | |
| 134 | ## Open a work item |
| 135 | |
| 136 | On **Work**, choose **New work item**. Give it a title and a description, |
| 137 | and pick the repositories it should land in, as targets: none, one or |
| 138 | several. Opened from a repository's **Work** tab, that repository is its |
| 139 | origin. |
| 140 | |
| 141 | From the CLI, `g1t work new` opens one in the current repository's |
| 142 | workspace, with the repository as its origin: |
| 143 | |
| 144 | ```sh |
| 145 | g1t work new --title "Sign-in times out on slow networks" --body "…" |
| 146 | ``` |
| 147 | |
| 148 | `--workspace` opens one in a workspace with no repository as its origin. |
| 149 | |
| 150 | ## Work on one |
| 151 | |
| 152 | Claims, hand-offs, dependencies and sessions are how people and coding |
| 153 | agents work on a work item at once without getting in each other's way; |
| 154 | see [sessions, claims and dependencies](/guides/sessions/). A session is |
| 155 | recorded in the repository it is checked out in, and the work item it |
| 156 | works on is the workspace's. |
| 157 | |
| 158 | To open a pull request for a work item, use `g1t pr create --item 12`, or |
| 159 | the `pull_request` tool's `create` with `item: 12`. The pull request's |
| 160 | repository becomes touched on the work item, and the pull request lands it |
| 161 | there when it merges. |
| 162 | |
| 163 | ## The CLI |
| 164 | |
| 165 | `g1t work` works on the current repository's workspace, or the one in |
| 166 | `--workspace`. Every command takes `--json`. |
| 167 | |
| 168 | | Command | Does | |
| 169 | | --- | --- | |
| 170 | | `g1t work list` | Lists open work items. `--repo`, `--state`, `--label`, `--milestone`, `--assignee` narrow it. | |
| 171 | | `g1t work view N` | Shows the work item with everything about its work: its repositories and what landed, claims, sessions, pull requests, what blocks it, decisions. | |
| 172 | | `g1t work new` | Opens a work item. | |
| 173 | | `g1t work edit N` | Changes its title, description, labels, assignees or milestone. | |
| 174 | | `g1t work close N` | Closes it, as completed, or `--reason not_planned`. | |
| 175 | | `g1t work reopen N` | Opens it again. | |
| 176 | | `g1t work link N` | Links a repository in a role: `--role target` (the default), with the current repository or `--repo owner/name`. | |
| 177 | | `g1t work unlink N` | Unlinks a repository. | |
| 178 | | `g1t work claim N` | Says you are working on it. With `--title` instead of a number, opens a work item and claims it. | |
| 179 | | `g1t work release N` | Lets go of your claim. | |
| 180 | | `g1t work handoff N` | Hands it to someone else, or to anyone, with a note. | |
| 181 | | `g1t work status` | The repository's active claims and sessions. | |
| 182 | |
| 183 | [CLI commands](/reference/cli/#g1t-work) lists every flag. |
| 184 | |
| 185 | ## MCP and the API |
| 186 | |
| 187 | The MCP server's `work_item` tool takes an `action`: `list`, `get`, |
| 188 | `create`, `update`, `close`, `reopen`, `link`, `unlink`, `comment`, |
| 189 | `claim`, `release`, `handoff`, `work` and `import`, among others. It takes |
| 190 | `workspace` and `number`; `repo` is optional, as the origin of a new work |
| 191 | item, a filter, or to find the workspace. See [MCP tools](/reference/mcp/). |
| 192 | |
| 193 | The REST API has the same under `/workspaces/{workspace}/work`: |
| 194 | |
| 195 | | To | REST | |
| 196 | | --- | --- | |
| 197 | | List work items | `GET /workspaces/{workspace}/work` | |
| 198 | | Open one | `POST /workspaces/{workspace}/work` | |
| 199 | | Get one | `GET /workspaces/{workspace}/work/{number}` | |
| 200 | | Change one | `PATCH /workspaces/{workspace}/work/{number}` | |
| 201 | | Close or reopen it | `POST /workspaces/{workspace}/work/{number}/close`, `…/reopen` | |
| 202 | | Link or unlink a repository | `POST` or `DELETE /workspaces/{workspace}/work/{number}/links` | |
| 203 | | Comment | `POST /workspaces/{workspace}/work/{number}/comments` | |
| 204 | | Its work context | `GET /workspaces/{workspace}/work/{number}/work` | |
| 205 | | Claim, release, hand off | `POST /workspaces/{workspace}/work/{number}/claim`, `…/release`, `…/handoff` | |
| 206 | | A repository's work items | `GET /repos/{owner}/{name}/work` | |
| 207 | |
| 208 | ```sh |
| 209 | curl -X POST https://api.g1t.sh/workspaces/acme/work \ |
| 210 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 211 | -H "Content-Type: application/json" \ |
| 212 | -d '{"title": "Sign-in times out", "repo": "acme/web", "targets": ["acme/web", "acme/api"]}' |
| 213 | ``` |
| 214 | |
| 215 | A work item has `workspace`, `number`, `title`, `body`, `state`, `reason`, |
| 216 | `labels`, `milestone`, `assignees`, `blocked_by`, `repos` (each with |
| 217 | `path`, `role`, `landed` and, for one that was an issue, its |
| 218 | `legacy_number`) and `resolutions` (each with `repo` and the `pull` or |
| 219 | `commit` that landed it). Changing work items needs a token with |
| 220 | `work:write`. |
| 221 | |
| 222 | Every change is an event, `work_item.opened`, `work_item.closed` and so |
| 223 | on, sent to [webhooks](/guides/webhooks/): a repository's webhooks for the |
| 224 | work items linked to it, a workspace's for all of them. |