Docs: work items, a guide of their own and a note on how issues became them
A new Work items guide says what a work item is: the workspace's, with one number sequence shared with new pull requests, linked to repositories as origin, target or touched, closed once every target has landed, with Part of #N for a pull request that does only part. It covers who sees one, the Work list, the CLI's g1t work commands, the work_item MCP tool and the REST routes under /workspaces/{workspace}/work. Issues became work items says what happened to existing issues, labels and milestones, that old links still resolve, and what scripts and agents must change. How g1t works, Labels, Milestones and the pull requests guide's closing section (now Closing work items) say the same. The sidebar lists both new pages, and the old issue operations' API reference pages redirect to the work item ones.
- G1T-Session:
- ses_01m561b3cvee8r1mnkn21gpgs1
7 files+564−2090/7 viewed
| 37 | 37 | '/guides/memory/': '/guides/bring-your-own-agent/', | |
| 38 | 38 | '/guides/spend/': '/guides/usage-and-billing/', | |
| 39 | 39 | '/guides/outcomes/': '/guides/milestones/', | |
| 40 | + | // Issues became workspace work items: their operations moved with them. | |
| 41 | + | '/reference/api/issues/list-issues/': '/reference/api/work-items/list-work-items/', | |
| 42 | + | '/reference/api/issues/create-issue/': '/reference/api/work-items/open-work-item/', | |
| 43 | + | '/reference/api/issues/get-issue/': '/reference/api/work-items/get-work-item/', | |
| 44 | + | '/reference/api/issues/update-issue/': '/reference/api/work-items/update-work-item/', | |
| 45 | + | '/reference/api/issues/close-issue/': '/reference/api/work-items/close-work-item/', | |
| 46 | + | '/reference/api/issues/reopen-issue/': '/reference/api/work-items/reopen-work-item/', | |
| 47 | + | '/reference/api/integrations/import-issue/': '/reference/api/work-items/import-work-items/', | |
| 40 | 48 | }, | |
| 41 | 49 | integrations: [ | |
| 42 | 50 | starlight({ | |
| ⋯ | |||
| 104 | 112 | { label: 'How g1t works', slug: 'concepts/overview' }, | |
| 105 | 113 | { label: 'The g1t CLI', slug: 'guides/cli' }, | |
| 106 | 114 | { label: 'Home', slug: 'guides/home' }, | |
| 115 | + | { label: 'Work items', slug: 'guides/work-items' }, | |
| 107 | 116 | { label: 'Ask g1t', slug: 'guides/ask' }, | |
| 108 | 117 | { label: 'AI providers', slug: 'guides/ai' }, | |
| 109 | 118 | { label: 'Notifications', slug: 'guides/notifications' }, | |
| ⋯ | |||
| 248 | 257 | label: 'About', | |
| 249 | 258 | items: [ | |
| 250 | 259 | { label: "What g1t can't do yet", slug: 'about/limitations' }, | |
| 260 | + | { label: 'Issues became work items', slug: 'about/issues-became-work-items' }, | |
| 251 | 261 | { label: 'An open letter to Cloudflare', slug: 'about/open-letter-to-cloudflare' }, | |
| 252 | 262 | ], | |
| 253 | 263 | }, | |
| 1 | + | --- | |
| 2 | + | title: Issues became work items | |
| 3 | + | description: Issues moved out of repositories into workspace-level work items. What happened to the issues, labels and milestones you had, why old links still work, and what to change in scripts and agents. | |
| 4 | + | --- | |
| 5 | + | ||
| 6 | + | Issues used to belong to one repository each. They are now | |
| 7 | + | [work items](/guides/work-items/), which belong to the workspace and can | |
| 8 | + | link several repositories. **Work**, after **Home** in the left rail, | |
| 9 | + | replaces each repository's **Issues** tab. | |
| 10 | + | ||
| 11 | + | ## What happened to your issues | |
| 12 | + | ||
| 13 | + | Every issue became a work item, with everything it had: its title and | |
| 14 | + | description, comments, reactions, labels, assignees, milestone, claims, | |
| 15 | + | sessions, pull requests and what it was blocked by. | |
| 16 | + | ||
| 17 | + | - **It has a new number.** Work items are numbered once for the whole | |
| 18 | + | workspace, and each issue was given the next number, oldest first, above | |
| 19 | + | every number any of the workspace's repositories had used. So an issue | |
| 20 | + | number and a work item number never mean two things. | |
| 21 | + | - **Its repository is its origin.** The work item links the repository | |
| 22 | + | the issue was in as its `origin`, and keeps the old number there. Its | |
| 23 | + | pull requests' repositories are linked as `touched`. | |
| 24 | + | - **Pull requests kept their numbers.** New ones take the workspace's next | |
| 25 | + | number. | |
| 26 | + | - **Who can see it did not change.** Anyone who could read the repository | |
| 27 | + | still sees the work item filed there. Members of the workspace now see | |
| 28 | + | every work item in it. | |
| 29 | + | ||
| 30 | + | ## Old links still work | |
| 31 | + | ||
| 32 | + | - `g1t.sh/<owner>/<repo>/issues/12` redirects to the work item that issue | |
| 33 | + | became, at `g1t.sh/<owner>/-/work/<number>`. **Issues**, **New issue**, | |
| 34 | + | **Labels** and **Milestones** under a repository redirect to **Work**. | |
| 35 | + | - `#12` and `owner/repo#12` in descriptions, comments and commit messages | |
| 36 | + | written before still link to that issue's work item. | |
| 37 | + | - `Closes #12` in history still points at the right work item. | |
| 38 | + | - A repository's old **Work** page, its claims and sessions, is now its | |
| 39 | + | **Sessions** page, and the old address redirects there. | |
| 40 | + | ||
| 41 | + | ## Labels and milestones | |
| 42 | + | ||
| 43 | + | Labels and milestones now belong to the workspace, too. | |
| 44 | + | ||
| 45 | + | - Labels with the same name in several repositories became one label. The | |
| 46 | + | one made first kept its color and description. | |
| 47 | + | - Milestones were renumbered in the workspace. Each records the | |
| 48 | + | repository it came from, and every work item and pull request in it | |
| 49 | + | stayed in it. | |
| 50 | + | ||
| 51 | + | ## What to change | |
| 52 | + | ||
| 53 | + | Nothing that reads links or references needs to change. What calls g1t by | |
| 54 | + | name does: | |
| 55 | + | ||
| 56 | + | | Was | Now | | |
| 57 | + | | --- | --- | | |
| 58 | + | | `g1t issue …` | `g1t work …`: `list`, `view`, `new`, `edit`, `close`, `reopen` | | |
| 59 | + | | `g1t work context N` | `g1t work view N` | | |
| 60 | + | | `g1t work list` (claims and sessions) | `g1t work status` | | |
| 61 | + | | `--issue N` on `g1t pr create`, `g1t session …` and `g1t work events` | `--item N` | | |
| 62 | + | | The MCP `issue` tool | `work_item`, with `workspace` and `number` | | |
| 63 | + | | `pull_request` `create` with `issue` | `pull_request` `create` with `item` | | |
| 64 | + | | `/repos/{owner}/{name}/issues…` | `/workspaces/{workspace}/work…` | | |
| 65 | + | | Repository labels and milestones routes | `/workspaces/{workspace}/labels` and `/workspaces/{workspace}/milestones` | | |
| 66 | + | | `issue.*` events and webhooks | `work_item.*`. Webhooks you had were moved over for you. | | |
| 67 | + | | `issues:read`, `issues:write` scopes | `work:read`, `work:write` | | |
| 68 | + | | `/g1t:work-on-issue` in Claude Code | `/g1t:work-on-item`, with the plugin 0.3.0 and the CLI 0.4.0 or later | | |
| 69 | + | ||
| 70 | + | There are no aliases for the old names: a script that calls one gets an | |
| 71 | + | error, not a silent change. Numbers in your own data, such as a tracker | |
| 72 | + | that stored `owner/repo#12`, still resolve, but a work item's own number | |
| 73 | + | is the one to keep from now on. |
| 1 | 1 | --- | |
| 2 | 2 | title: How g1t works | |
| 3 | − | description: How Code works on g1t, and how issues, pull requests, checks, review, merging and sessions fit together, for people and coding agents alike. | |
| 3 | + | description: How Code works on g1t, and how work items, pull requests, checks, review, merging and sessions fit together, for people and coding agents alike. | |
| 4 | 4 | --- | |
| 5 | 5 | ||
| 6 | − | A workspace holds your repositories, with issues, pull requests, required | |
| 7 | − | checks and the merge queue; [Actions](/guides/actions/) that run your | |
| 6 | + | A workspace holds your repositories and the work items that say what | |
| 7 | + | should change in them, with pull requests, required checks and the merge | |
| 8 | + | queue; [Actions](/guides/actions/) that run your | |
| 8 | 9 | workflows; [Deployments](/guides/deployments/) that put every pull request | |
| 9 | 10 | live; and [Chat](/guides/chat/) for your team. This page is about | |
| 10 | 11 | **Code**, where changes are made and landed. | |
| 11 | 12 | ||
| 12 | 13 | Underneath is ordinary git: clone, branch, commit, push and pull work as | |
| 13 | 14 | they do anywhere. On top of it are the two things you already know, | |
| 14 | − | **issues** and **pull requests**, built so that many people and coding | |
| 15 | + | **work items** and **pull requests**, built so that many people and coding | |
| 15 | 16 | agents can work at once without getting in each other's way. | |
| 16 | 17 | ||
| 17 | 18 | The coding agents you already use, such as Claude Code, Codex, Cursor or | |
| ⋯ | |||
| 23 | 24 | ||
| 24 | 25 | | | What it is | | |
| 25 | 26 | | --- | --- | | |
| 26 | − | | **Issue** | What should change: a bug, a feature, a question. | | |
| 27 | − | | **Pull request** | A proposed change, on a branch or in a working copy of its own. Usually made for an issue. | | |
| 28 | − | | **Session** | One run of a coding agent: its prompts, reasoning and tool calls, tied to the issue and pull request it worked on. | | |
| 27 | + | | **Work item** | What should change: a feature, a bug, a chore. It belongs to the workspace and can land in several repositories. | | |
| 28 | + | | **Pull request** | A proposed change to one repository, on a branch or in a working copy of its own. Usually made for a work item. | | |
| 29 | + | | **Session** | One run of a coding agent: its prompts, reasoning and tool calls, tied to the work item and pull request it worked on. | | |
| 29 | 30 | ||
| 30 | − | One issue can have several pull requests, each from a different person or | |
| 31 | − | agent, and g1t keeps track of which one was merged. | |
| 31 | + | One work item can have several pull requests, in one repository or in | |
| 32 | + | several, each from a different person or agent, and g1t keeps track of | |
| 33 | + | which ones were merged and where the work has landed. | |
| 32 | 34 | ||
| 33 | − | ## Issues | |
| 35 | + | ## Work items | |
| 34 | 36 | ||
| 35 | − | An issue says what should change in a repository. People open them, | |
| 36 | − | coding agents open them, and so can anything with an access token, such | |
| 37 | − | as an error tracker reporting a crash. | |
| 37 | + | A work item says what should change. People open them, coding agents open | |
| 38 | + | them, and so can anything with an access token, such as an error tracker | |
| 39 | + | reporting a crash. They are under **Work**, after **Home** in the left | |
| 40 | + | rail; see [work items](/guides/work-items/). | |
| 38 | 41 | ||
| 39 | − | An issue has: | |
| 42 | + | A work item has: | |
| 40 | 43 | ||
| 41 | 44 | - a **title** and a **description** in Markdown. Whoever works on the | |
| 42 | − | issue, person or agent, works from this text. Say what done means in | |
| 45 | + | work item, person or agent, works from this text. Say what done means in | |
| 43 | 46 | plain words, under a `## Definition of done` heading if you like: it is | |
| 44 | 47 | context for whoever works on it and its reviewers, not something a merge | |
| 45 | 48 | waits on; | |
| 46 | − | - **labels**, which say what kind of issue it is; | |
| 49 | + | - its **repositories**: the one it was filed in (its `origin`), the ones | |
| 50 | + | it should land in (its `targets`), and the ones a pull request or commit | |
| 51 | + | for it has `touched`; | |
| 52 | + | - **labels**, which say what kind of work it is; | |
| 47 | 53 | - **comments** and **assignees**; | |
| 48 | − | - a **state**: open or closed. A closed issue records why: `completed` or | |
| 49 | − | `not_planned`. | |
| 54 | + | - a **state**: open or closed. A closed work item records why: | |
| 55 | + | `completed` or `not_planned`. | |
| 50 | 56 | ||
| 51 | − | Issues and pull requests share one sequence of numbers per repository, so | |
| 52 | − | `#12` names exactly one of them. | |
| 57 | + | Work items and pull requests share one sequence of numbers per workspace, | |
| 58 | + | so `#12` names exactly one of them, whichever repository you are in. | |
| 53 | 59 | ||
| 54 | − | A new repository starts with a set of labels such as `bug`, | |
| 55 | − | `enhancement` and `question`; anyone with the Triage role can make more as | |
| 56 | − | they label. An issue or pull request carries up to 20. See | |
| 57 | − | [labels](/guides/labels/). | |
| 60 | + | A workspace starts with a set of labels such as `bug`, `enhancement` and | |
| 61 | + | `question`, shared by all its repositories; anyone with the Triage role | |
| 62 | + | can make more as they label. A work item or pull request carries up to 20. | |
| 63 | + | See [labels](/guides/labels/). | |
| 58 | 64 | ||
| 59 | 65 | ## Pull requests | |
| 60 | 66 | ||
| ⋯ | |||
| 66 | 72 | it is opened. | |
| 67 | 73 | ||
| 68 | 74 | **In a working copy.** This is how coding agents usually work: the | |
| 69 | − | `pull_request` tool's `create` action, or `g1t pr create --issue 12` with | |
| 70 | − | no branch of your own, opens a draft pull request for an issue and makes | |
| 75 | + | `pull_request` tool's `create` action with `item`, or | |
| 76 | + | `g1t pr create --item 12` with no branch of your own, opens a draft pull | |
| 77 | + | request for a work item and makes | |
| 71 | 78 | it a copy of the repository that belongs to that pull request alone, | |
| 72 | 79 | ready in about the time a branch would be. The author clones it, commits | |
| 73 | 80 | and pushes to it, and nothing they do can touch `main` or another pull | |
| ⋯ | |||
| 84 | 91 | | `merged` | Landed on its base branch. | | |
| 85 | 92 | | `closed` | Closed without merging. | | |
| 86 | 93 | ||
| 87 | − | A pull request is normally opened **for an issue**. It can also stand | |
| 88 | − | alone, with its own title, for a change nobody filed an issue about. | |
| 94 | + | A pull request is normally opened **for a work item**. It can also stand | |
| 95 | + | alone, with its own title, for a change nobody filed a work item about. | |
| 89 | 96 | ||
| 90 | 97 | ## Assignees and reviewers | |
| 91 | 98 | ||
| 92 | − | Issues and pull requests have assignees, and pull requests have | |
| 99 | + | Work items and pull requests have assignees, and pull requests have | |
| 93 | 100 | reviewers: the people and teams whose review was asked for. Each shows | |
| 94 | 101 | beside the conversation, with where every reviewer stands. | |
| 95 | 102 | ||
| 96 | − | Assigning an issue to `g1t`, or mentioning `@g1t` in a comment, starts a | |
| 103 | + | Assigning a work item to `g1t`, or mentioning `@g1t` in a comment, starts a | |
| 97 | 104 | session on the workspace's own Anthropic account, as the person who asked; | |
| 98 | 105 | see [Assign g1t](/guides/sessions/#assign-g1t-or-ask-it-in-the-thread). | |
| 99 | 106 | ||
| ⋯ | |||
| 101 | 108 | assigned whom, whose review was asked for, which sessions started, and | |
| 102 | 109 | when it was marked ready, merged or closed. | |
| 103 | 110 | ||
| 104 | − | ## Several pull requests for one issue | |
| 111 | + | ## Several pull requests for one work item | |
| 105 | 112 | ||
| 106 | − | An issue can have more than one pull request: a second attempt after the | |
| 107 | − | first fell short, or two agents trying different approaches. Each has its | |
| 108 | − | own branch or working copy, its own session and its own diff. The issue's | |
| 109 | − | page lists them all with their status. | |
| 113 | + | A work item can have more than one pull request: one in each repository | |
| 114 | + | it has to land in, a second attempt after the first fell short, or two | |
| 115 | + | agents trying different approaches. Each has its own branch or working | |
| 116 | + | copy, its own session and its own diff. The work item's page lists them | |
| 117 | + | all, by repository, with their status. | |
| 110 | 118 | ||
| 111 | 119 | When you merge one: | |
| 112 | 120 | ||
| 113 | 121 | - the pull request becomes `merged`, recording who merged it and when; | |
| 114 | − | - the issue closes as `completed`, and records that pull request as the one | |
| 115 | − | that **resolved** it; | |
| 116 | − | - every other pull request for that issue that was still a draft or open is | |
| 117 | − | closed, marked as **superseded** by the one that was merged. | |
| 122 | + | - its repository is marked **landed** on the work item, which records that | |
| 123 | + | pull request as the one that **resolved** it there; | |
| 124 | + | - every other pull request for that work item in the same repository that | |
| 125 | + | was still a draft or open is closed, marked as **superseded** by the one | |
| 126 | + | that was merged; | |
| 127 | + | - the work item closes as `completed` once every repository it targets | |
| 128 | + | has landed, or at once when it has no targets. | |
| 118 | 129 | ||
| 119 | − | So the answer to "which one did we take?" is on the issue, on the merged | |
| 120 | − | pull request, and on each one that was passed over. | |
| 130 | + | So the answer to "which one did we take?" is on the work item, on the | |
| 131 | + | merged pull request, and on each one that was passed over. | |
| 121 | 132 | ||
| 122 | − | When several pull requests each do part of an issue, say that the issue | |
| 123 | − | should stay open as you merge. The pull request merges, and the issue and | |
| 124 | − | the other pull requests are left as they are. | |
| 133 | + | When several pull requests in one repository each do part of the work, | |
| 134 | + | say `Part of #12` in all but the last, or say that the work item should | |
| 135 | + | stay open as you merge. The pull request merges, and the work item and the | |
| 136 | + | other pull requests are left as they are. | |
| 125 | 137 | ||
| 126 | 138 | ## Checks | |
| 127 | 139 | ||
| ⋯ | |||
| 157 | 169 | which files each pull request changes, from every push, and shows on a | |
| 158 | 170 | pull request which others in progress change the same ones. | |
| 159 | 171 | ||
| 160 | − | Two pull requests for the *same* issue are expected to overlap: they are | |
| 161 | − | alternatives, and one will be merged. Two for *different* issues are | |
| 172 | + | Two pull requests for the *same* work item in one repository are expected | |
| 173 | + | to overlap: they are alternatives, and one will be merged. Two for | |
| 174 | + | *different* work items are | |
| 162 | 175 | heading for a conflict, and g1t says so while the work is still going on, | |
| 163 | 176 | not when the second one tries to merge. Agents get the same list from the | |
| 164 | 177 | `pull_request` tool's `get` action, as `overlaps`, so they can keep their | |
| ⋯ | |||
| 204 | 217 | reasoning, the tools it called, and what it touched. g1t's | |
| 205 | 218 | [Claude Code plugin](/guides/claude-code-plugin/) records one for every | |
| 206 | 219 | Claude Code session in a g1t repository; other agents record theirs with | |
| 207 | − | the `session` tool or `g1t session`. A session is tied to the issue it | |
| 208 | − | claimed and the pull request it opened, and people read it on the pull | |
| 209 | − | request's **Session** tab and on the repository's **Work** page, which | |
| 210 | − | shows who is working on what right now. See | |
| 220 | + | the `session` tool or `g1t session`. A session is recorded in the repository it | |
| 221 | + | is checked out in, and tied to the work item it claimed and the pull | |
| 222 | + | request it opened. People read it on the pull request's **Session** tab, | |
| 223 | + | on the work item, and on the repository's **Sessions** page, which shows | |
| 224 | + | who is working on what right now. See | |
| 211 | 225 | [sessions, claims and dependencies](/guides/sessions/). | |
| 212 | 226 | ||
| 213 | 227 | Each entry is tied to the commit that was the head when it was recorded, | |
| 214 | 228 | so **Blame** on any file can show not only the commit that last changed a | |
| 215 | − | line, but the pull request and issue it came from and the agent's own | |
| 229 | + | line, but the pull request and work item it came from and the agent's own | |
| 216 | 230 | account of the change. See [sessions and why-blame](/guides/why-blame/). | |
| 217 | 231 | ||
| 218 | 232 | ## Events | |
| 219 | 233 | ||
| 220 | − | Every state change in g1t is published as an event: a push, an issue being | |
| 234 | + | Every state change in g1t is published as an event: a push, a work item being | |
| 221 | 235 | opened, a pull request being merged, a session growing. Events reach the | |
| 222 | 236 | services that react to them, your [webhooks](/guides/webhooks/), and a | |
| 223 | 237 | timeline per repository that you can read through the | |
| 1 | 1 | --- | |
| 2 | 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. | |
| 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 | 4 | --- | |
| 5 | 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. | |
| 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. | |
| 10 | 11 | ||
| 11 | − | ## The labels a repository starts with | |
| 12 | + | ## The labels a workspace starts with | |
| 12 | 13 | ||
| 13 | − | A new repository starts with these: | |
| 14 | + | A new workspace starts with these: | |
| 14 | 15 | ||
| 15 | 16 | | Label | Color | Description | | |
| 16 | 17 | | --- | --- | --- | | |
| 17 | 18 | | `bug` | `d73a4a` | Something isn't working | | |
| 18 | 19 | | `documentation` | `0075ca` | Improvements or additions to documentation | | |
| 19 | − | | `duplicate` | `cfd3d7` | This issue or pull request already exists | | |
| 20 | + | | `duplicate` | `cfd3d7` | This work item or pull request already exists | | |
| 20 | 21 | | `enhancement` | `a2eeef` | New feature or request | | |
| 21 | 22 | | `good first issue` | `7057ff` | Good for newcomers | | |
| 22 | 23 | | `help wanted` | `008672` | Extra attention is needed | | |
| ⋯ | |||
| 26 | 27 | | `dependencies` | `0366d6` | Updates a dependency | | |
| 27 | 28 | | `security` | `ee0701` | A security fix or a vulnerability | | |
| 28 | 29 | ||
| 29 | − | A repository made before labels had colors kept every label its issues | |
| 30 | − | already carried. To give it the defaults too: | |
| 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](/about/issues-became-work-items/#labels-and-milestones). | |
| 34 | + | To add the defaults a workspace lacks: | |
| 31 | 35 | ||
| 32 | − | 1. Open the project's **Issues**, then **Labels**. | |
| 36 | + | 1. Open **Work**, then **Labels**. | |
| 33 | 37 | 2. Choose **Add the default labels**. | |
| 34 | 38 | ||
| 35 | − | Labels the repository has already are left as they are. | |
| 39 | + | Labels the workspace has already are left as they are. | |
| 36 | 40 | ||
| 37 | − | ## Put labels on an issue or a pull request | |
| 41 | + | ## Put labels on a work item or a pull request | |
| 38 | 42 | ||
| 39 | − | 1. Open the issue or pull request. | |
| 43 | + | 1. Open the work item or pull request. | |
| 40 | 44 | 2. In the sidebar, choose the settings icon beside **Labels**. | |
| 41 | 45 | 3. Tick labels on and off. Type to find one by its name or description. | |
| 42 | 46 | 4. Close the menu. The labels save as it closes. | |
| 43 | 47 | ||
| 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 | |
| 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 | |
| 46 | 50 | `pull.unlabeled` on a pull request). | |
| 47 | 51 | ||
| 48 | 52 | Who may do this: | |
| 49 | 53 | ||
| 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. | |
| 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. | |
| 52 | 56 | - 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 | |
| 57 | + | label anything, and make a label as they go: type a name the workspace | |
| 54 | 58 | does not have, and choose **Create**. | |
| 55 | 59 | ||
| 56 | − | An issue or a pull request carries at most 20 labels. | |
| 60 | + | A work item or a pull request carries at most 20 labels. | |
| 57 | 61 | ||
| 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. | |
| 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. | |
| 60 | 64 | ||
| 61 | 65 | ## Filter by a label | |
| 62 | 66 | ||
| 63 | − | On **Issues** or **Pull requests**, choose **Label** and pick one. The | |
| 67 | + | On **Work** or **Pull requests**, choose **Label** and pick one. The | |
| 64 | 68 | address keeps it, as `?label=bug`, so the filtered list can be shared. You | |
| 65 | 69 | can also write it as `?q=label:bug`, with quotes around a name with | |
| 66 | 70 | spaces: `?q=label:"good first issue"`. **Clear filters** shows everything | |
| 67 | 71 | again. | |
| 68 | 72 | ||
| 69 | − | ## Manage a repository's labels | |
| 73 | + | ## Manage the workspace's labels | |
| 70 | 74 | ||
| 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 | |
| 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 | |
| 73 | 77 | requests carry it; choose a count to see them. Search finds a label by its | |
| 74 | 78 | name or description. | |
| 75 | 79 | ||
| 76 | − | With the Write role or higher you can (applying labels needs only Triage): | |
| 80 | + | With the Write role in the workspace or higher you can (applying labels | |
| 81 | + | needs only Triage): | |
| 77 | 82 | ||
| 78 | 83 | | To | Do this | | |
| 79 | 84 | | --- | --- | | |
| 80 | 85 | | 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. | | |
| 86 | + | | Change one | **Edit**. Renaming a label renames it on every work item and pull request that carries it, in every repository. | | |
| 82 | 87 | | Delete one | **Delete**. It comes off everything that carries it. This cannot be undone. | | |
| 83 | 88 | ||
| 84 | − | Names are lowercase and unique in a repository: `Bug` and `bug` are the | |
| 89 | + | Names are lowercase and unique in a workspace: `Bug` and `bug` are the | |
| 85 | 90 | same label. | |
| 86 | 91 | ||
| 87 | 92 | ## Labels and g1t | |
| 88 | 93 | ||
| 89 | 94 | - [Dependency updates](/guides/dependency-updates/) carry `dependencies` | |
| 90 | 95 | and their ecosystem's label (`javascript`, `rust`, `go`, `python`, …) | |
| 91 | − | unless `labels` in the file says otherwise. Labels the repository lacks | |
| 96 | + | unless `labels` in the file says otherwise. Labels the workspace lacks | |
| 92 | 97 | are made for them. | |
| 93 | 98 | - [Workflows](/guides/actions/) can start on `labeled` and `unlabeled` | |
| 94 | − | activity of `issues` and `pull_request`. | |
| 99 | + | activity of `pull_request`. | |
| 95 | 100 | ||
| 96 | 101 | ## From the API | |
| 97 | 102 | ||
| 98 | 103 | | To | REST | MCP | | |
| 99 | 104 | | --- | --- | --- | | |
| 100 | − | | List labels | `GET /repos/{owner}/{name}/labels` | `repository` `list_labels` | | |
| 101 | − | | Make one | `POST /repos/{owner}/{name}/labels` | `repository` `create_label` | | |
| 102 | − | | Change one | `PATCH /repos/{owner}/{name}/labels/{label}` | `repository` `update_label` | | |
| 103 | − | | Delete one | `DELETE /repos/{owner}/{name}/labels/{label}` | `repository` `delete_label` | | |
| 104 | − | | Add the defaults | `POST /repos/{owner}/{name}/labels/defaults` | `repository` `add_default_labels` | | |
| 105 | − | | An item's labels | `GET /repos/{owner}/{name}/issues/{number}/labels` | `issue` `labels` | | |
| 106 | − | | Add labels | `POST /repos/{owner}/{name}/issues/{number}/labels` | `issue` `add_labels` | | |
| 107 | − | | Replace them | `PUT /repos/{owner}/{name}/issues/{number}/labels` | `issue` `set_labels` | | |
| 108 | − | | Take one off | `DELETE /repos/{owner}/{name}/issues/{number}/labels/{label}` | `issue` `remove_labels` | | |
| 109 | − | | Take all off | `DELETE /repos/{owner}/{name}/issues/{number}/labels` | `issue` `remove_labels` | | |
| 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 | 110 | ||
| 111 | − | The `issues/{number}/labels` routes work on pull requests too, since issues | |
| 112 | − | and pull requests share numbers. URL-encode a label's spaces in a path: | |
| 113 | − | `good%20first%20issue`. | |
| 111 | + | URL-encode a label's spaces in a path: `good%20first%20issue`. | |
| 114 | 112 | ||
| 115 | 113 | ```sh | |
| 116 | − | curl -X POST https://api.g1t.sh/repos/acme/web/issues/12/labels \ | |
| 114 | + | curl -X POST https://api.g1t.sh/workspaces/acme/labels \ | |
| 117 | 115 | -H "Authorization: Bearer $G1T_TOKEN" \ | |
| 118 | 116 | -H "Content-Type: application/json" \ | |
| 119 | − | -d '{"labels": ["bug", "help wanted"]}' | |
| 117 | + | -d '{"name": "needs design", "color": "fbca04"}' | |
| 120 | 118 | ``` | |
| 121 | 119 | ||
| 122 | − | `labels` on `create_issue`, `update_issue` and `update_pull_request` set | |
| 123 | − | them as well, and `label` filters `list_issues` and `list_pull_requests`. | |
| 124 | − | Managing labels needs a token with `issues:write`. | |
| 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`. | |
| 1 | 1 | --- | |
| 2 | 2 | title: Milestones | |
| 3 | − | description: Gather issues and pull requests under a goal and a due date, and see how much of it is done. | |
| 3 | + | description: Gather work items and pull requests from across your workspace under a goal and a due date, and see how much of it is done. | |
| 4 | 4 | --- | |
| 5 | 5 | ||
| 6 | − | A milestone gathers issues and pull requests under one goal, such as a | |
| 7 | − | release, with an optional due date. Its page shows everything in it and how | |
| 8 | − | far along it is: the share of its issues and pull requests that are | |
| 9 | − | closed. A merged pull request counts as closed. | |
| 6 | + | A milestone gathers work items and pull requests under one goal, such as a | |
| 7 | + | release, with an optional due date. Milestones belong to the workspace, so | |
| 8 | + | one can hold work from any of its repositories. Its page shows everything | |
| 9 | + | in it and how far along it is: the share of its work items and pull | |
| 10 | + | requests that are closed. A merged pull request counts as closed. | |
| 10 | 11 | ||
| 11 | 12 | ## Make a milestone | |
| 12 | 13 | ||
| 13 | − | You need the Triage [role](/guides/access-and-roles/) or higher. | |
| 14 | + | You need the Triage [role](/guides/access-and-roles/) in the workspace or | |
| 15 | + | higher. | |
| 14 | 16 | ||
| 15 | − | 1. Open the project's **Issues**, then **Milestones**. | |
| 17 | + | 1. Open **Work**, then **Milestones**. | |
| 16 | 18 | 2. Choose **New milestone**. | |
| 17 | − | 3. Give it a title, unique in the repository, and if you like a due date | |
| 19 | + | 3. Give it a title, unique in the workspace, and if you like a due date | |
| 18 | 20 | and a description. The description is Markdown. | |
| 19 | 21 | 4. Choose **Create milestone**. | |
| 20 | 22 | ||
| 21 | − | Milestones are numbered from 1 in each repository, apart from issues and | |
| 22 | − | pull requests. The number is in its address: | |
| 23 | − | `g1t.sh/<owner>/<repo>/milestones/3`. | |
| 23 | + | Milestones are numbered from 1 in each workspace, apart from work items | |
| 24 | + | and pull requests. The number is in its address: | |
| 25 | + | `g1t.sh/<workspace>/-/work/milestones/3`. | |
| 26 | + | ||
| 27 | + | Milestones used to belong to each repository. When they moved to the | |
| 28 | + | workspace they were numbered again, and each records the repository it | |
| 29 | + | came from; see | |
| 30 | + | [Issues became work items](/about/issues-became-work-items/#labels-and-milestones). | |
| 24 | 31 | ||
| 25 | − | ## Put an issue or a pull request in one | |
| 32 | + | ## Put a work item or a pull request in one | |
| 26 | 33 | ||
| 27 | − | 1. Open the issue or pull request. | |
| 34 | + | 1. Open the work item or pull request. | |
| 28 | 35 | 2. In the sidebar, choose the settings icon beside **Milestone**. | |
| 29 | 36 | 3. Pick a milestone, or **Clear milestone** to take it out. | |
| 30 | 37 | ||
| 31 | 38 | An item is in at most one milestone. Moving it is noted in the | |
| 32 | − | conversation, and is an `issue.milestoned` or `issue.demilestoned` event | |
| 33 | − | (`pull.milestoned` and `pull.demilestoned` on a pull request). With the | |
| 34 | − | Triage role you can also choose a milestone on **New issue**. | |
| 39 | + | conversation, and is a `work_item.milestoned` or `work_item.demilestoned` | |
| 40 | + | event (`pull.milestoned` and `pull.demilestoned` on a pull request). With | |
| 41 | + | the Triage role you can also choose a milestone on **New work item**. | |
| 35 | 42 | ||
| 36 | 43 | ## Follow its progress | |
| 37 | 44 | ||
| ⋯ | |||
| 40 | 47 | shows its due date, how many of its items are open and closed, and a bar | |
| 41 | 48 | of how much is done. One whose due date has passed says how late it is. | |
| 42 | 49 | ||
| 43 | − | A milestone's page lists its open and closed issues and pull requests, | |
| 44 | − | newest first. On **Issues** or **Pull requests**, choose **Milestone** to | |
| 45 | − | filter the list by one; the address keeps it as `?milestone=3`. | |
| 50 | + | A milestone's page lists its open and closed work items and pull | |
| 51 | + | requests, newest first. On **Work** or **Pull requests**, choose | |
| 52 | + | **Milestone** to filter the list by one; the address keeps it as | |
| 53 | + | `?milestone=3`. | |
| 46 | 54 | ||
| 47 | 55 | ## Change, close or delete one | |
| 48 | 56 | ||
| 49 | − | With the Write role or higher, on **Milestones** or a milestone's page (putting an issue in one needs only Triage): | |
| 57 | + | With the Write role in the workspace or higher, on **Milestones** or a | |
| 58 | + | milestone's page (putting a work item in one needs only Triage): | |
| 50 | 59 | ||
| 51 | 60 | | To | Do this | | |
| 52 | 61 | | --- | --- | | |
| ⋯ | |||
| 58 | 67 | ||
| 59 | 68 | | To | REST | MCP | | |
| 60 | 69 | | --- | --- | --- | | |
| 61 | − | | List milestones | `GET /repos/{owner}/{name}/milestones`, `state` to filter | `repository` `list_milestones` | | |
| 62 | − | | Get one with its items | `GET /repos/{owner}/{name}/milestones/{milestone}` | `repository` `get_milestone` | | |
| 63 | − | | Make one | `POST /repos/{owner}/{name}/milestones` | `repository` `create_milestone` | | |
| 64 | − | | Change one | `PATCH /repos/{owner}/{name}/milestones/{milestone}` | `repository` `update_milestone` | | |
| 65 | − | | Delete one | `DELETE /repos/{owner}/{name}/milestones/{milestone}` | `repository` `delete_milestone` | | |
| 70 | + | | List milestones | `GET /workspaces/{workspace}/milestones`, `state` to filter | `workspace` `list_milestones` | | |
| 71 | + | | Get one with its items | `GET /workspaces/{workspace}/milestones/{milestone}` | `workspace` `get_milestone` | | |
| 72 | + | | Make one | `POST /workspaces/{workspace}/milestones` | `workspace` `create_milestone` | | |
| 73 | + | | Change one | `PATCH /workspaces/{workspace}/milestones/{milestone}` | `workspace` `update_milestone` | | |
| 74 | + | | Delete one | `DELETE /workspaces/{workspace}/milestones/{milestone}` | `workspace` `delete_milestone` | | |
| 66 | 75 | ||
| 67 | 76 | A milestone has `number`, `title`, `description`, `due_on` (`YYYY-MM-DD`), | |
| 68 | 77 | `state` (`open` or `closed`), `open_items` and `closed_items`. Send | |
| 69 | 78 | `"due_on": ""` to clear a due date, and `"state": "closed"` to close it. | |
| 70 | 79 | ||
| 71 | 80 | ```sh | |
| 72 | − | curl -X POST https://api.g1t.sh/repos/acme/web/milestones \ | |
| 81 | + | curl -X POST https://api.g1t.sh/workspaces/acme/milestones \ | |
| 73 | 82 | -H "Authorization: Bearer $G1T_TOKEN" \ | |
| 74 | 83 | -H "Content-Type: application/json" \ | |
| 75 | 84 | -d '{"title": "Launch", "due_on": "2026-10-14"}' | |
| 76 | 85 | ``` | |
| 77 | 86 | ||
| 78 | − | `milestone`, a milestone's number, puts an item in it on `create_issue`, | |
| 79 | − | `update_issue` and `update_pull_request`; `null` or `0` takes it out. | |
| 80 | − | Issues and pull requests carry `milestone` as `{"number", "title"}`, and | |
| 81 | − | `milestone` filters `list_issues` and `list_pull_requests`. Managing | |
| 82 | − | milestones needs a token with `issues:write`. | |
| 87 | + | `milestone`, a milestone's number, puts an item in it when you open or | |
| 88 | + | change a work item (`POST /workspaces/{workspace}/work`, | |
| 89 | + | `PATCH /workspaces/{workspace}/work/{number}`) and on | |
| 90 | + | `update_pull_request`; `null` or `0` takes it out. Work items and pull | |
| 91 | + | requests carry `milestone` as `{"number", "title"}`, and `milestone` | |
| 92 | + | filters `list_work_items` and `list_pull_requests`. Managing milestones | |
| 93 | + | needs a token with `work:write`. | |
| 83 | 94 | ||
| 84 | 95 | [Dependency updates](/guides/dependency-updates/) put their pull requests | |
| 85 | 96 | in the milestone their entry's `milestone` names. | |
| 1 | 1 | --- | |
| 2 | 2 | title: Pull requests and checks | |
| 3 | − | description: What the merge box shows before a pull request can merge, the checks your workflows report and which ones a merge needs, reviewers, sessions, how a large change's files load, drafts, closing and reopening, editing and deleting comments, merge methods, commit messages, auto-merge, merging by pushing, closing issues, deleting branches, comments on commits, conflicts, and keeping a branch up to date. | |
| 3 | + | description: What the merge box shows before a pull request can merge, the checks your workflows report and which ones a merge needs, reviewers, sessions, how a large change's files load, drafts, closing and reopening, editing and deleting comments, merge methods, commit messages, auto-merge, merging by pushing, closing work items, deleting branches, comments on commits, conflicts, and keeping a branch up to date. | |
| 4 | 4 | --- | |
| 5 | 5 | ||
| 6 | 6 | At the foot of an open pull request's conversation, the **merge box** says | |
| ⋯ | |||
| 46 | 46 | **Details** to its log. It is there to read; nothing in it can be re-run, | |
| 47 | 47 | and it says nothing about merging. | |
| 48 | 48 | ||
| 49 | − | ### Other attempts at the same issue | |
| 49 | + | ### Other attempts at the same work item | |
| 50 | 50 | ||
| 51 | − | When an issue has more than one pull request, for example because two | |
| 52 | − | people or two coding agents each tried it, every one of them shows **Other attempts at #N**: the | |
| 53 | − | pull requests for that issue side by side, this one first. Each row has its | |
| 51 | + | When a work item has more than one pull request in a repository, for | |
| 52 | + | example because two people or two coding agents each tried it, every one | |
| 53 | + | of them shows **Other attempts at #N**: the pull requests for that work | |
| 54 | + | item in the repository side by side, this one first. Each row has its | |
| 54 | 55 | state (open, merged, or closed because another was merged instead), its | |
| 55 | 56 | head commit's checks, where its review stands, its size, and the files it | |
| 56 | − | changes that this one changes too. Pull requests for the same issue are | |
| 57 | + | changes that this one changes too. Pull requests for the same work item are | |
| 57 | 58 | alternatives, so they are not listed under **Other work is changing the | |
| 58 | − | same files**; that box is for work on other issues, which will collide. | |
| 59 | + | same files**; that box is for work on other work items, which will | |
| 60 | + | collide. | |
| 59 | 61 | ||
| 60 | 62 | ### Running them again | |
| 61 | 63 | ||
| ⋯ | |||
| 203 | 205 | ||
| 204 | 206 | ## Sessions | |
| 205 | 207 | ||
| 206 | − | Each session that works on a pull request, or on its issue, shows in the | |
| 208 | + | Each session that works on a pull request, or on its work item, shows in the | |
| 207 | 209 | conversation as a card where it started, the way a comment or a review | |
| 208 | 210 | does: who it is (or g1t, working for someone), where it stands, its | |
| 209 | 211 | branch, and its report once it ends, linked to its page. Mention `@g1t` | |
| ⋯ | |||
| 297 | 299 | ||
| 298 | 300 | ## Editing and deleting comments | |
| 299 | 301 | ||
| 300 | − | You can edit and delete your own comments on issues and pull requests. | |
| 302 | + | You can edit and delete your own comments on work items and pull requests. | |
| 301 | 303 | Anyone with the Maintain [role](/guides/access-and-roles/) or higher can | |
| 302 | 304 | edit and delete anyone's. | |
| 303 | 305 | ||
| ⋯ | |||
| 311 | 313 | edit, so it has neither. The notes in the timeline of what happened, | |
| 312 | 314 | such as "closed this", cannot be edited or deleted. | |
| 313 | 315 | ||
| 314 | − | Through the API, `PATCH /repos/{owner}/{name}/issues/comments/{comment_id}` | |
| 315 | − | with `body` edits a comment and answers with it, and | |
| 316 | − | `DELETE /repos/{owner}/{name}/issues/comments/{comment_id}` deletes it and | |
| 317 | − | answers `204`. Both work for comments on issues and on pull requests; each | |
| 318 | − | comment's `id` is in `GET /repos/{owner}/{name}/issues/{number}` and | |
| 316 | + | Through the API, `PATCH /workspaces/{workspace}/work/comments/{comment_id}` | |
| 317 | + | with `body` edits a work item's comment and answers with it, and | |
| 318 | + | `DELETE /workspaces/{workspace}/work/comments/{comment_id}` deletes it and | |
| 319 | + | answers `204`; `PATCH` and `DELETE` | |
| 320 | + | `/repos/{owner}/{name}/pulls/comments/{comment_id}` do the same for a pull | |
| 321 | + | request's. Each comment's `id` is in | |
| 322 | + | `GET /workspaces/{workspace}/work/{number}` and | |
| 319 | 323 | `GET /repos/{owner}/{name}/pulls/{number}`. On the MCP server they are the | |
| 320 | − | `issue` tool's `edit_comment` and `delete_comment` actions. Editing | |
| 324 | + | `work_item` and `pull_request` tools' `edit_comment` and `delete_comment` | |
| 325 | + | actions. Editing | |
| 321 | 326 | publishes `comment.edited`, with what the comment said before in | |
| 322 | 327 | `changes.body.from`; deleting publishes `comment.deleted`, with the comment | |
| 323 | 328 | as it was in `comment`. | |
| 324 | 329 | ||
| 325 | 330 | ## Reactions | |
| 326 | 331 | ||
| 327 | − | React to an issue's or pull request's description, or to any comment on | |
| 332 | + | React to a work item's or pull request's description, or to any comment on | |
| 328 | 333 | it, with one of eight emoji: 👍 👎 😄 🎉 😕 ❤️ 🚀 👀. Select the smiley | |
| 329 | 334 | under it, or a reaction already there to add or take back yours; hovering | |
| 330 | − | one says who reacted. Anyone who can read the repository may react. g1t | |
| 335 | + | one says who reacted. Anyone who can read it may react. g1t | |
| 331 | 336 | reacts 👀 to what it was asked to take on. | |
| 332 | 337 | ||
| 333 | − | Through the API, `POST /repos/{owner}/{name}/issues/{number}/reactions` | |
| 334 | − | with `content` (`+1`, `-1`, `laugh`, `hooray`, `confused`, `heart`, | |
| 338 | + | Through the API, `POST /workspaces/{workspace}/work/{number}/reactions` | |
| 339 | + | (or `POST /repos/{owner}/{name}/pulls/{number}/reactions`) with `content` (`+1`, `-1`, `laugh`, `hooray`, `confused`, `heart`, | |
| 335 | 340 | `rocket` or `eyes`), and `comment_id` to react to a comment rather than | |
| 336 | 341 | the description, reacts and answers with the reactions it has now; | |
| 337 | − | `remove: true` takes yours back. On the MCP server it is the `issue` | |
| 338 | − | tool's `react` action. Each comment's `reactions`, and the description's, | |
| 339 | − | are in `GET /repos/{owner}/{name}/issues/{number}` and | |
| 342 | + | `remove: true` takes yours back. On the MCP server it is the `work_item` | |
| 343 | + | and `pull_request` tools' `react` action. Each comment's `reactions`, and | |
| 344 | + | the description's, are in `GET /workspaces/{workspace}/work/{number}` and | |
| 340 | 345 | `GET /repos/{owner}/{name}/pulls/{number}`: each with its `content`, | |
| 341 | 346 | `count` and the `users` who reacted. | |
| 342 | 347 | ||
| 343 | 348 | ## Images | |
| 344 | 349 | ||
| 345 | − | To show an image in a pull request's or an issue's description, or in a | |
| 350 | + | To show an image in a pull request's or a work item's description, or in a | |
| 346 | 351 | comment (a screenshot of a preview, say), upload it and paste the Markdown | |
| 347 | 352 | you get back. From a shell, `g1t attach preview.png` prints | |
| 348 | 353 | ``, and `--attach | |
| 349 | 354 | preview.png` on `g1t pr create`, `g1t pr ready`, `g1t pr comment`, | |
| 350 | − | `g1t issue create` and `g1t issue comment` adds it for you (see the | |
| 355 | + | `g1t work new` and `g1t work comment` adds it for you (see the | |
| 351 | 356 | [CLI guide](/guides/cli/#images-in-descriptions-and-comments)). Through the API it is | |
| 352 | 357 | `POST /repos/{owner}/{name}/attachments` with `name`, the file | |
| 353 | 358 | base64-encoded in `data`, and optionally `content_type`; it answers with | |
| 354 | 359 | `id`, `url`, `content_type`, `size` and `markdown`. On the MCP server it is | |
| 355 | − | the `issue` tool's `attach` action. | |
| 360 | + | the `work_item` tool's `attach` action. | |
| 356 | 361 | ||
| 357 | 362 | An attachment is a PNG, JPEG, GIF or WebP image of at most 10 MB, judged by | |
| 358 | 363 | its bytes: a larger file is refused with `413` (`too_large`), anything else | |
| 359 | 364 | with `415` (`unsupported_type`). Anyone who may comment on the repository | |
| 360 | − | may upload one, with `issues:write`. It is served from g1t's usercontent | |
| 365 | + | may upload one, with `work:write`. It is served from g1t's usercontent | |
| 361 | 366 | address, never g1t.sh, and its address is its permission: anyone given the | |
| 362 | 367 | link can see the image, even one from a private repository. A purged | |
| 363 | 368 | repository's attachments are deleted with it. | |
| ⋯ | |||
| 385 | 390 | | Delete | `DELETE /repos/{owner}/{name}/comments/{comment_id}`, which answers `204` | `delete_commit_comment` | | |
| 386 | 391 | ||
| 387 | 392 | Reading needs the `repo:read` scope; commenting, editing and deleting need | |
| 388 | − | `issues:write`, as comments on issues do. Each publishes | |
| 393 | + | `work:write`, as comments on work items do. Each publishes | |
| 389 | 394 | `commit_comment.created`, `commit_comment.edited` or | |
| 390 | 395 | `commit_comment.deleted` to [webhooks](/guides/webhooks/). | |
| 391 | 396 | ||
| ⋯ | |||
| 458 | 463 | | `{base}` | The branch it merges into | | |
| 459 | 464 | | `{author}` | Its author's username | | |
| 460 | 465 | | `{commits}` | Its commits' subjects, one `* subject` line each | | |
| 461 | − | | `{issues}` | The issues it closes, as `#12, #14` | | |
| 466 | + | | `{items}` | The work items it lands on, as `#12, #14` | | |
| 462 | 467 | | `{co_authors}` | A `Co-authored-by:` line for each author of its commits, each once | | |
| 463 | 468 | ||
| 464 | 469 | ```text | |
| ⋯ | |||
| 466 | 471 | ||
| 467 | 472 | {body} | |
| 468 | 473 | ||
| 469 | − | Closes {issues} | |
| 474 | + | Closes {items} | |
| 470 | 475 | {co_authors} | |
| 471 | 476 | ``` | |
| 472 | 477 | ||
| ⋯ | |||
| 505 | 510 | the head commit of an open pull request into that branch (a draft too), | |
| 506 | 511 | the pull request is marked merged, by whoever pushed, with `merge_commit` | |
| 507 | 512 | set to the commit the branch was pushed to. It is the same as any other | |
| 508 | − | merge: the issues it closes close, the other pull requests for its issue | |
| 509 | − | close as superseded, it leaves the merge queue, and `pull.merged` is | |
| 513 | + | merge: it lands on the work items it closes, the other pull requests for | |
| 514 | + | its work item in the repository close as superseded, it leaves the merge queue, and `pull.merged` is | |
| 510 | 515 | published. Its timeline says **merged this by pushing** that commit **to** | |
| 511 | 516 | the branch. | |
| 512 | 517 | ||
| ⋯ | |||
| 515 | 520 | already held before the push (a branch opened at a commit of the base, with | |
| 516 | 521 | nothing on it yet) does not merge it either. Its branch is not deleted. | |
| 517 | 522 | ||
| 518 | − | ### Closing issues | |
| 523 | + | ### Closing work items | |
| 519 | 524 | ||
| 520 | − | When a pull request merges into the default branch, it closes the issue it | |
| 521 | − | was made for and every issue its title or description names after a | |
| 522 | − | closing keyword: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, | |
| 523 | − | `resolve`, `resolves` or `resolved`, in any case, with or without a colon: | |
| 525 | + | When a pull request merges into the default branch, it lands its | |
| 526 | + | repository on the work item it was made for, and on every work item its | |
| 527 | + | title or description names after a closing keyword: `close`, `closes`, | |
| 528 | + | `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves` or `resolved`, in | |
| 529 | + | any case, with or without a colon: | |
| 524 | 530 | ||
| 525 | 531 | ```text | |
| 526 | − | Fixes #12. Resolves: #14, closes acme/web#15 | |
| 532 | + | Fixes #12. Resolves: #14, closes acme/api#15 | |
| 527 | 533 | ``` | |
| 528 | 534 | ||
| 529 | − | An issue in another repository is never closed: `owner/name#3` counts only | |
| 530 | − | when it names this one. The pull request's `closes` lists the issues it | |
| 531 | − | will close, in the order named. Merging into any other branch closes | |
| 532 | − | nothing. A repository can turn this off with `auto_close_issues`; the | |
| 533 | − | issues then stay open after the merge. | |
| 535 | + | Landing marks the pull request's repository as landed on the work item and | |
| 536 | + | records a resolution: the repository and the pull request. The work item | |
| 537 | + | closes as completed when it has no target repositories, or once every | |
| 538 | + | target has landed; until then it stays open, and its page says which | |
| 539 | + | targets are missing. See [work items](/guides/work-items/#closing-a-work-item). | |
| 540 | + | ||
| 541 | + | `Part of #12` (also `Part of acme/api#12`, or `Refs #12`) links the pull | |
| 542 | + | request to the work item, and its repository as touched, without landing | |
| 543 | + | anything: use it for a pull request that does only part of a repository's | |
| 544 | + | share. | |
| 545 | + | ||
| 546 | + | `#12` and `owner/name#12` name work items of the repository's own | |
| 547 | + | workspace, whichever of its repositories they are written in. A work item | |
| 548 | + | of another workspace is never closed. The pull request's `closes` lists | |
| 549 | + | the work items it will land on, in the order named, and `parts` the ones it | |
| 550 | + | is part of. Merging into any other branch lands nothing. A repository can | |
| 551 | + | turn this off with `auto_close_items`; its pull requests then land nothing | |
| 552 | + | when they merge. | |
| 534 | 553 | ||
| 535 | − | Commit messages close issues the same way. When a push to the default | |
| 536 | − | branch brings in a commit whose message names an issue after a closing | |
| 537 | − | keyword, that issue closes as completed. This applies to commits pushed | |
| 538 | − | directly, merged in a clone, or landed by a pull request, and up to 250 | |
| 539 | − | commits per push are read. The issue's timeline says who pushed it and | |
| 540 | − | **closed this in** that commit, its page shows **Closed by commit**, and | |
| 541 | − | the commit's page lists the issues it closed. `issue.closed` carries the | |
| 542 | − | commit as `commit`, and an issue has `resolved_commit` and | |
| 543 | − | `resolved_pushed_by`; reopening it clears both. A push that makes a new | |
| 544 | − | branch reads none of its commits, since they were pushed before, except a | |
| 545 | − | repository's first push, which makes its default branch: `Closes #1` in | |
| 546 | − | the first version of a new repository closes #1. Commits pushed to other | |
| 547 | − | branches close nothing until they reach the default branch, and | |
| 548 | − | `auto_close_issues` turns this off as well. | |
| 554 | + | Commit messages land work items the same way. When a push to the default | |
| 555 | + | branch brings in a commit whose message names a work item after a closing | |
| 556 | + | keyword, the commit's repository lands on it. This applies to commits | |
| 557 | + | pushed directly, merged in a clone, or landed by a pull request, and up to | |
| 558 | + | 250 commits per push are read. The work item's timeline says who pushed | |
| 559 | + | it and **landed this in** that commit, its page shows the commit beside | |
| 560 | + | the repository, and the commit's page lists the work items it landed on. | |
| 561 | + | The resolution records the commit as `commit` and who pushed it as | |
| 562 | + | `pushed_by`, and `work_item.closed`, when it closes, carries the commit as | |
| 563 | + | `commit`; reopening a work item clears its resolutions. A push that makes | |
| 564 | + | a new branch reads none of its commits, since they were pushed before, | |
| 565 | + | except a repository's first push, which makes its default branch: | |
| 566 | + | `Closes #1` in the first version of a new repository lands on #1. Commits | |
| 567 | + | pushed to other branches land nothing until they reach the default branch, | |
| 568 | + | and `auto_close_items` turns this off as well. | |
| 549 | 569 | ||
| 550 | − | A commit that is already on the default branch can close an issue later, | |
| 551 | − | say one pushed before the issue was open or while `auto_close_issues` was | |
| 552 | − | off: [`close_issue`](/reference/api/issues/close-issue/) with `commit` (its | |
| 553 | − | full hash), `g1t issue close 12 --commit <hash>`, or the `issue` tool's | |
| 554 | − | `close` with `commit`. The commit's message must name the issue after a | |
| 555 | − | closing keyword. The issue then closes as completed in that commit, the way | |
| 556 | − | a push of it would have, by whoever closed it: **closed this in** the | |
| 557 | − | commit, `resolved_commit`, and `issue.closed` with `commit`. A commit that is | |
| 558 | − | not on the default branch, or whose message does not name the issue, is | |
| 559 | − | refused, and so is an issue that is already closed. | |
| 570 | + | A commit that is already on the default branch can land a work item later, | |
| 571 | + | say one pushed before the work item was open or while `auto_close_items` | |
| 572 | + | was off: [`close_work_item`](/reference/api/work-items/close-work-item/) | |
| 573 | + | with `repo` and `commit` (its full hash), `g1t work close 12 --commit | |
| 574 | + | <hash>` in the repository, or the `work_item` tool's `close` with `repo` | |
| 575 | + | and `commit`. The commit's message must name the work item after a closing | |
| 576 | + | keyword. Its repository then lands in that commit, the way a push of it | |
| 577 | + | would have, by whoever did it. A commit that is not on the default branch, | |
| 578 | + | or whose message does not name the work item, is refused, and so is a work | |
| 579 | + | item that is already closed. | |
| 560 | 580 | ||
| 561 | − | An issue's timeline links whatever closed it: **closed this in** a commit | |
| 562 | − | links the commit, **closed this by merging #14** links the pull request, | |
| 563 | − | and when it was closed in a [session](/guides/sessions/) the line ends | |
| 564 | − | **via session**, linking that session. That session is the one the closing | |
| 565 | − | commit names in a `G1t-Session: ses_…` trailer, or, for an issue closed | |
| 566 | − | with a token (from an agent, the CLI or the MCP server), the closer's own | |
| 567 | − | session on the issue that is still going. `issue.closed` carries it as | |
| 568 | − | `session`. An issue closed on the site says only who closed it. | |
| 581 | + | A work item's timeline links whatever landed it: **landed this in** a | |
| 582 | + | commit links the commit, **landed this by merging #14** links the pull | |
| 583 | + | request, and when it was done in a [session](/guides/sessions/) the line | |
| 584 | + | ends **via session**, linking that session. That session is the one the | |
| 585 | + | closing commit names in a `G1t-Session: ses_…` trailer, or, for a work item | |
| 586 | + | closed with a token (from an agent, the CLI or the MCP server), the | |
| 587 | + | closer's own session on the work item that is still going. | |
| 588 | + | `work_item.closed` carries it as `session`. A work item closed on the site | |
| 589 | + | says only who closed it. | |
| 569 | 590 | ||
| 570 | − | Wherever a commit's message shows, `#12` links to that issue or pull | |
| 571 | − | request, with its title and state when you hover over it. | |
| 591 | + | Wherever a commit's message shows, `#12` links to that work item or pull | |
| 592 | + | request, with its title and state when you hover over it. Old issue | |
| 593 | + | numbers written before work items still link to the work item each became. | |
| 572 | 594 | ||
| 573 | 595 | ### Deleting the branch | |
| 574 | 596 | ||
| ⋯ | |||
| 720 | 742 | | `behind` | Whether its target has moved on without it. | | |
| 721 | 743 | | `merge_method`, `merge_commit` | Once merged: how, and the commit its base was left at. | | |
| 722 | 744 | | `auto_merge` | When auto-merge is on: `method`, `commit_title`, `commit_message`, `enabled_by` and `enabled_at`. | | |
| 723 | − | | `closes` | The issues it closes when it merges into the default branch. | | |
| 745 | + | | `item` | The number of the work item it was made for. | | |
| 746 | + | | `closes`, `parts` | The work items it lands on when it merges into the default branch, and the ones it is part of. | | |
| 724 | 747 | | `head_branch_deleted` | Whether its branch was deleted after it merged or closed. | | |
| 725 | 748 | | `reviewers`, `team_reviewers` | The people and the [teams](/guides/teams/#review-requests) asked to review it. | | |
| 726 | 749 | | `code_owners` | Who owns the files it changes and whose approval is still needed; see [CODEOWNERS](/guides/codeowners/#through-the-api). Absent when its target has no CODEOWNERS file. | | |
| 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. |
Comments
Sign in to comment.