Merge branch 'worktree-agent-af2cbc96b80d702e5' into work-items
- G1T-Session:
- ses_01m560bz6eeqc8v1hrrha03pap
79 files+1534−98915 files not counted0/79 viewed
| 6 | 6 | { | |
| 7 | 7 | "name": "g1t", | |
| 8 | 8 | "source": "./plugins/claude-code", | |
| 9 | − | "description": "Work on g1t issues from Claude Code: records your sessions on g1t, loads an issue's work context, claims and hands off work, and connects g1t's MCP server.", | |
| 10 | − | "version": "0.2.11", | |
| 9 | + | "description": "Work on g1t work items from Claude Code: records your sessions on g1t, loads a work item's work context, claims and hands off work, and connects g1t's MCP server.", | |
| 10 | + | "version": "0.3.0", | |
| 11 | 11 | "category": "development" | |
| 12 | 12 | } | |
| 13 | 13 | ] |
| 1 | 1 | # Contributing to g1t | |
| 2 | 2 | ||
| 3 | − | g1t is built the way it asks others to build: issues and pull requests on | |
| 3 | + | g1t is built the way it asks others to build: work items and pull requests on | |
| 4 | 4 | [g1t.sh/flagon-io/g1t](https://g1t.sh/flagon-io/g1t), required checks that prove | |
| 5 | 5 | a change works, and a merge queue that keeps `main` passing. | |
| 6 | 6 |
| 61 | 61 | ||
| 62 | 62 | - **Sessions.** Record a coding agent as it works: its | |
| 63 | 63 | prompts, tool calls, subagents, branches, commits and pull requests. Work | |
| 64 | − | that is not an issue yet is a session titled by what it is for. The | |
| 64 | + | that is not a work item yet is a session titled by what it is for. The | |
| 65 | 65 | [Claude Code plugin](https://docs.g1t.sh/guides/claude-code-plugin/) does | |
| 66 | 66 | it automatically after installation and sign-in; other clients can record | |
| 67 | 67 | summaries with the CLI or MCP, including through the Codex plugin skill. | |
| 68 | 68 | - **Live now.** A project's page shows who is working on it right now and | |
| 69 | − | with which harness, grouped by issue, pull request or branch. | |
| 70 | − | - **Claims.** Advisory, expiring claims on issues, so two agents don't do the | |
| 69 | + | with which harness, grouped by work item, pull request or branch. | |
| 70 | + | - **Claims.** Advisory, expiring claims on work items, so two agents don't do the | |
| 71 | 71 | same work, with hand-offs between sessions and coordination events | |
| 72 | 72 | (`g1t work events --follow`, or over MCP) when work overlaps. | |
| 73 | 73 | - **Integration.** The merge queue tests changes together before they land, | |
| 74 | 74 | tests smaller combinations to narrow a failure without assuming a single | |
| 75 | 75 | culprit, and sends the evidence to the session responsible for repair. | |
| 76 | 76 | - **Why-blame and decisions.** `g1t why file:line` answers why code is as it | |
| 77 | − | is: its commit, pull request, issue, the decisions recorded along the way, | |
| 77 | + | is: its commit, pull request, work item, the decisions recorded along the way, | |
| 78 | 78 | and the sessions behind it. | |
| 79 | 79 | - **Ask g1t.** Ask about your work from any page, or by messaging @g1t. It | |
| 80 | 80 | answers with your workspace's own AI provider and reads g1t as you. | |
| ⋯ | |||
| 82 | 82 | ### Code | |
| 83 | 83 | ||
| 84 | 84 | - Public and private repositories, git over HTTPS, creating a repository by | |
| 85 | − | pushing to it, GitHub import (every branch and tag, and issues). | |
| 86 | − | - Issues, milestones, labels, pull requests, line comments and reviews. | |
| 85 | + | pushing to it, GitHub import (every branch and tag, and issues, as work items). | |
| 86 | + | - Work items that belong to the workspace and can span its repositories, | |
| 87 | + | with milestones and labels; pull requests, line comments and reviews. | |
| 87 | 88 | - Required checks, rulesets, CODEOWNERS and the merge queue. | |
| 88 | 89 | - Workflows from `.g1t/workflows` in GitHub Actions syntax, on g1t's Linux | |
| 89 | 90 | runners or self-hosted ones on Linux, macOS and Windows, with caches, | |
| ⋯ | |||
| 129 | 130 | | `apps/sudo` | g1t's own staff console. | TypeScript | | |
| 130 | 131 | | `services/identity` | Accounts, workspaces, sessions, keys, tokens and invites. | Rust | | |
| 131 | 132 | | `services/repos` | Repository registry, contents, forks, diffs, landing, git over HTTPS. | Rust | | |
| 132 | − | | `services/work` | Issues, pull requests, reviews, check runs, agent sessions, claims and the merge queue. | Rust | | |
| 133 | + | | `services/work` | Work items, pull requests, reviews, check runs, agent sessions, claims and the merge queue. | Rust | | |
| 133 | 134 | | `services/events` | The event bus and its log. | Rust | | |
| 134 | 135 | | `services/search` | Site-wide search and Explore. | Rust | | |
| 135 | 136 | | `services/billing` | Usage, the price book, limits, invoices and payments. | Rust | | |
| ⋯ | |||
| 180 | 181 | ``` | |
| 181 | 182 | ||
| 182 | 183 | Then open <http://localhost:8787> and sign up. The confirmation mail is in | |
| 183 | − | Mailpit at <http://localhost:8025>. Repositories, push and clone, issues, | |
| 184 | + | Mailpit at <http://localhost:8025>. Repositories, push and clone, work items, | |
| 184 | 185 | pull requests, code browsing, search, webhooks and observability work, and | |
| 185 | 186 | the API and MCP server answer at <http://localhost:8789>; packages and | |
| 186 | 187 | container images are kept in the bundled S3-compatible store, RustFS. | |
| 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. |
| 377 | 377 | request, as for [pushes](#pushes-up-to-100-mb-each). The step warns and | |
| 378 | 378 | the job goes on; smaller and larger entries are saved. | |
| 379 | 379 | - `on: label`: creating, editing or deleting a label starts no workflows. | |
| 380 | − | Putting a label on an issue or a pull request starts `issues` and | |
| 380 | + | Putting a label on a work item or a pull request starts `work_item` and | |
| 381 | 381 | `pull_request` workflows with the `labeled` type. | |
| 382 | 382 | - The `pull_request` activity types `unassigned`, `locked`, `unlocked`, | |
| 383 | − | and `edited` for a new title or description, and the `issues` types | |
| 383 | + | and `edited` for a new title or description, and the `work_item` types | |
| 384 | 384 | `unassigned`, `locked`, `unlocked`, `pinned` and `unpinned`: g1t starts | |
| 385 | 385 | no workflows for them. | |
| 386 | 386 | ||
| ⋯ | |||
| 504 | 504 | ### Self-hosting is early | |
| 505 | 505 | ||
| 506 | 506 | [Running g1t yourself](/guides/self-hosting/) gives you the core forge: | |
| 507 | − | accounts, repositories over HTTP, issues and pull requests, the REST API | |
| 507 | + | accounts, repositories over HTTP, work items and pull requests, the REST API | |
| 508 | 508 | and MCP, container images, search, webhooks and observability. Hosted | |
| 509 | 509 | runners, deployments, billing and git over SSH are off. The merge queue | |
| 510 | 510 | can accept pull requests, but cannot test or land them without g1t's | |
| 6 | 6 | Dear Cloudflare, | |
| 7 | 7 | ||
| 8 | 8 | We're the small team at Flagon, Inc. building g1t, a git platform where | |
| 9 | − | people and coding agents work in the same issues, pull requests and merge | |
| 9 | + | people and coding agents work in the same work items, pull requests and merge | |
| 10 | 10 | queue. Every part of it runs on you: more than twenty-five Workers, a D1 database for | |
| 11 | 11 | each service that keeps data, Artifacts for every repository and every pull | |
| 12 | 12 | request's fork, Containers for agents and CI, R2, KV, Queues, and Cloudflare | |
| ⋯ | |||
| 33 | 33 | anywhere. | |
| 34 | 34 | ||
| 35 | 35 | The rest of the platform held up too. Rust compiled to WebAssembly runs our | |
| 36 | − | core (repositories, issues and pull requests, the API, security and | |
| 36 | + | core (repositories, work items and pull requests, the API, security and | |
| 37 | 37 | billing), and TypeScript the rest. D1's read replication is free and good. Containers gave us | |
| 38 | 38 | sandboxes in three sizes. With a cached credential and ref listing, a | |
| 39 | 39 | `git fetch` with nothing new answers in under half a second, and most of | |
| 28 | 28 | 1. **Trigger.** `actions` reads its event queue, `g1t-events-actions`, ten | |
| 29 | 29 | at a time (step 1), and matches each event to the workflows in | |
| 30 | 30 | `.g1t/workflows` at the commit the event is about (the default branch | |
| 31 | − | for schedules, issues and manual runs; `services/actions/src/sync.rs`). | |
| 31 | + | for schedules, work items and manual runs; `services/actions/src/sync.rs`). | |
| 32 | 32 | g1t never reads `.github/workflows`. The files are GitHub Actions | |
| 33 | 33 | syntax, unchanged; [GitHub | |
| 34 | 34 | Actions](/guides/actions/) lists what is supported. |
| 6 | 6 | import Aside from '../../../components/Aside.astro'; | |
| 7 | 7 | import Diagram from '../../../components/Diagram.astro'; | |
| 8 | 8 | ||
| 9 | − | Every state change in g1t is published as an event: a push, an issue | |
| 9 | + | Every state change in g1t is published as an event: a push, a work item | |
| 10 | 10 | opened, a pull request merged, a workflow finished, a workspace renamed. | |
| 11 | 11 | Services do not call each other to announce what happened. They publish, | |
| 12 | 12 | and the `events` service (`services/events`, Rust) delivers. | |
| ⋯ | |||
| 32 | 32 | `decision.recorded`). They reach webhooks and followers like any other | |
| 33 | 33 | ([Work and the merge queue](/architecture/work/#coordination)). | |
| 34 | 34 | ||
| 35 | + | A work item belongs to a workspace, not a repository, so its events | |
| 36 | + | (`work_item.opened`, `work_item.closed` and the rest) carry `workspace`, | |
| 37 | + | `number`, `item_id` and `repo_ids`, every repository linked to it, in | |
| 38 | + | `data`. Each of those repositories' webhooks gets them, and the | |
| 39 | + | workspace's webhooks get them all. | |
| 40 | + | ||
| 35 | 41 | Two fields in `data` matter everywhere: | |
| 36 | 42 | ||
| 37 | 43 | - `causedByJob` marks an event caused by a workflow's own token, so it | |
| ⋯ | |||
| 72 | 78 | | Queue | Read by | Gets | | |
| 73 | 79 | | --- | --- | --- | | |
| 74 | 80 | | `g1t-events-work` | `work` | `git.push`, `branch.renamed`, `repo.created`, `repo.archived`, `repo.default_branch_changed`, `pull.merged`, `comment.created` | | |
| 75 | − | | `g1t-events-runner` | `runner` | Pull request changes, `checks.completed`, `queue.changed`, `comment.created`, issue changes, `repo.archived` | | |
| 76 | − | | `g1t-events-actions` | `actions` | `git.push`, `git.deleted`, `pull.*`, `issue.*`, `comment.*`, `release.*`, deployments, `workflow.completed`, `repo.archived` | | |
| 81 | + | | `g1t-events-runner` | `runner` | Pull request changes, `checks.completed`, `queue.changed`, `comment.created`, work item changes, `repo.archived` | | |
| 82 | + | | `g1t-events-actions` | `actions` | `git.push`, `git.deleted`, `pull.*`, `work_item.*`, `comment.*`, `release.*`, deployments, `workflow.completed`, `repo.archived` | | |
| 77 | 83 | | `g1t-events-webhooks` | `webhooks` | Everything | | |
| 78 | 84 | | `g1t-events-security` | `security` | `git.push`, pull request changes, `comment.created`, `repo.created`, `repo.visibility_changed` | | |
| 79 | − | | `g1t-events-search` | `search` | `git.push`, `repo.*`, `issue.*`, `pull.*`, `user.*`, `workspace.*` | | |
| 85 | + | | `g1t-events-search` | `search` | `git.push`, `repo.*`, `work_item.*`, `pull.*`, `user.*`, `workspace.*` | | |
| 80 | 86 | | `g1t-events-deployments` | `deployments` | Pushes, the pull request lifecycle, workspace deletion and restore, and deployment statuses (what each production deployment shipped) | | |
| 81 | 87 | | `g1t-events-projects` | `projects` | Repositories, packages and deployments | | |
| 82 | 88 | | `g1t-events-repos` | `repos` | `pull.merged`, `pull.closed`, `pull.reopened`, deletions and restores | | |
| 83 | 89 | | `g1t-events-packages` | `packages` | `git.push`, `repo.visibility_changed`, workspace and team changes | | |
| 84 | − | | `g1t-events-integrations` | `integrations` | `issue.closed`, `pull.opened` | | |
| 90 | + | | `g1t-events-integrations` | `integrations` | `work_item.closed`, `pull.opened` | | |
| 85 | 91 | | `g1t-events-billing` | `billing` | Lifecycle events only | | |
| 86 | 92 | | `g1t-events-docs` | `artifacts` | `git.push`, `pull.merged` | | |
| 87 | 93 | ||
| 142 | 142 | ||
| 143 | 143 | ## Pull request forks | |
| 144 | 144 | ||
| 145 | − | A pull request made for an issue gets a fork of its own | |
| 145 | + | A pull request made for a work item gets a fork of its own | |
| 146 | 146 | ([Forks and working copies](/concepts/forks/)). `fork_for_pull` makes it in the | |
| 147 | 147 | same namespace as its source, as `pulls--<pull request id>`, with | |
| 148 | 148 | Artifacts' own fork of the default branch, and it is served at |
| 67 | 67 | | Repository | Read, Triage, Write, Maintain and Admin, given to a person, a team, or everyone in the workspace as its base permission | | |
| 68 | 68 | | Outside collaborators | A repository role for someone who is not a member | | |
| 69 | 69 | ||
| 70 | + | A [work item](/guides/work-items/) belongs to the workspace, so it has no | |
| 71 | + | repository role of its own. `item_role` gives the viewer the higher of | |
| 72 | + | their role through workspace membership and their permission on the work | |
| 73 | + | item's origin repository, if it has one. `can_item` and `check_item` judge | |
| 74 | + | it with the same table as `can` and `check`. So members see every work | |
| 75 | + | item, anyone who can read the origin repository sees the ones filed there, | |
| 76 | + | and a work item with no origin is seen only by members. Managing the | |
| 77 | + | workspace's labels and milestones takes the role through membership. | |
| 78 | + | ||
| 70 | 79 | The rules live in `crates/contracts/src/access.rs`; the grants live in | |
| 71 | 80 | `identity`. [Access and roles](/guides/access-and-roles/) explains each | |
| 72 | 81 | role from a person's side. |
| 115 | 115 | <LinkCard title="Services and contracts" href="/architecture/services/" icon="boxes" description="Every unit, what it owns, what it calls, and how calls work." /> | |
| 116 | 116 | <LinkCard title="Git" href="/architecture/git/" icon="git-branch" description="Where repositories live, the push path, caches and forks." /> | |
| 117 | 117 | <LinkCard title="Events" href="/architecture/events/" icon="radio-tower" description="The bus, the log, fan-out, webhooks and following live." /> | |
| 118 | − | <LinkCard title="Work and the merge queue" href="/architecture/work/" icon="git-merge" description="Issues, pull requests, checks, merging and the queue." /> | |
| 118 | + | <LinkCard title="Work and the merge queue" href="/architecture/work/" icon="git-merge" description="Work items, pull requests, checks, merging and the queue." /> | |
| 119 | 119 | <LinkCard title="Actions, runners and sandboxes" href="/architecture/compute/" icon="cpu" description="Workflow jobs, hosted and self-hosted, and what walls them in." /> | |
| 120 | 120 | <LinkCard title="Deployments and telemetry" href="/architecture/deployments/" icon="rocket" description="Apps on g1t.page, packages, and observability." /> | |
| 121 | 121 | <LinkCard title="Data and storage" href="/architecture/data/" icon="database" description="Who owns what, migrations, and the ports that make self-hosting work." /> |
| 23 | 23 | | `apps/docs` | Astro | front | `docs.g1t.sh`, these pages | Nothing | none | | |
| 24 | 24 | | `services/identity` | Rust | core | Accounts, sessions, workspaces, members, teams, repository roles, tokens, OAuth, device sign-in, 2FA | D1 `g1t`, the avatars KV | `artifacts`, `billing`, `chat`, `events`, `notify`, `projects`, `repos` | | |
| 25 | 25 | | `services/repos` | Rust | core | Repositories and git: smart HTTP, pre-receive checks, caches, forks, landing merges, releases, backups | D1 `g1t-repos`, the git store, the git cache KV, the packs and backups buckets | `billing`, `events`, `identity`, `security`, `work` | | |
| 26 | − | | `services/work` | Rust | core | Issues, pull requests, comments, reviews, labels, milestones, rulesets, checks, statuses, CODEOWNERS, the merge queue | D1 `g1t-work` | `actions`, `events`, `identity`, `repos` | | |
| 26 | + | | `services/work` | Rust | core | Work items, pull requests, comments, reviews, labels, milestones, rulesets, checks, statuses, CODEOWNERS, the merge queue | D1 `g1t-work` | `actions`, `events`, `identity`, `repos` | | |
| 27 | 27 | | `services/events` | Rust | core | The event bus and log, the audit log, the inbox | D1 `g1t-events`, the `g1t-events` queue and its subscriber queues | `billing`, `identity`, `notify`, `repos`, `work` | | |
| 28 | 28 | | `services/actions` | Rust | core | Workflows: reading them, triggering runs, planning jobs, secrets, self-hosted runners, logs | D1 `g1t-actions`; lists and expires the Actions cache bucket | `billing`, `deployments`, `events`, `identity`, `notify`, `projects`, `repos`, `runner`, `work` | | |
| 29 | 29 | | `services/runner` | TypeScript | core | Sandboxes on Cloudflare Containers, one per job, with their egress | The Container classes | `actions`, `billing`, `deployments`, `events`, `identity`, `repos`, `work` | | |
| ⋯ | |||
| 31 | 31 | | `services/pages` | TypeScript | edge | The dispatcher for `*.g1t.page` and custom domains | Nothing; reads the domains KV | none | | |
| 32 | 32 | | `services/packages` | Rust | core | npm, Cargo, Composer, Maven, NuGet, RubyGems, Go and container images | D1 `g1t-packages`, the packages bucket | `billing`, `events`, `identity`, `repos` | | |
| 33 | 33 | | `services/security` | Rust | core | Secret scanning, dependency alerts and updates, code scanning, the supply chain | D1 `g1t-security` | `actions`, `billing`, `events`, `identity`, `repos`, `runner`, `work` | | |
| 34 | − | | `services/search` | Rust | core | Site search over repositories, issues, pull requests, people and code | D1 `g1t-search`, its jobs queue | `billing`, `identity`, `repos`, `work` | | |
| 34 | + | | `services/search` | Rust | core | Site search over repositories, work items, pull requests, people and code | D1 `g1t-search`, its jobs queue | `billing`, `identity`, `repos`, `work` | | |
| 35 | 35 | | `services/projects` | TypeScript | core | Projects and what they depend on | D1 `g1t-projects` | `deployments`, `events`, `identity`, `og`, `packages`, `repos` | | |
| 36 | 36 | | `services/chat` | TypeScript | core | Channels, direct messages and threads, live | D1 `g1t-chat`, a Durable Object per channel | `identity`, `integrations`, `notify` | | |
| 37 | 37 | | `services/artifacts` | TypeScript | core | Docs written together, live, with their spaces, sharing and search | D1 `g1t-docs`, its files bucket, two Vectorize indexes, a Durable Object per open doc | `billing`, `events`, `identity`, `notify`, `repos`, `work` | | |
| 1 | 1 | --- | |
| 2 | 2 | title: Work and the merge queue | |
| 3 | − | description: How the work service keeps issues, pull requests, checks and rulesets, coordinates sessions and claims, decides and lands a merge, and tests many changes at once in the merge queue. | |
| 3 | + | description: How the work service keeps work items, pull requests, checks and rulesets, coordinates sessions and claims, decides and lands a merge, and tests many changes at once in the merge queue. | |
| 4 | 4 | --- | |
| 5 | 5 | ||
| 6 | 6 | import Aside from '../../../components/Aside.astro'; | |
| 7 | 7 | import Diagram from '../../../components/Diagram.astro'; | |
| 8 | 8 | ||
| 9 | 9 | `work` (`services/work`, Rust) keeps everything about a change that is not | |
| 10 | − | the code itself: issues, pull requests, comments, reviews, labels, | |
| 10 | + | the code itself: work items, pull requests, comments, reviews, labels, | |
| 11 | 11 | milestones, rulesets, checks and commit statuses, CODEOWNERS, and the | |
| 12 | 12 | merge queue. Its database is `g1t-work`. The code lives in `repos`, and | |
| 13 | 13 | `work` asks `repos` whenever it needs it. | |
| 14 | 14 | ||
| 15 | − | ## Issues and pull requests | |
| 15 | + | ## Work items and pull requests | |
| 16 | 16 | ||
| 17 | − | Issues and pull requests share one sequence of numbers per repository | |
| 18 | − | (the `counters` table), so `#12` names exactly one of them. A pull request | |
| 19 | − | records where its head is: a fork of its own, `pulls--<id>` in the git | |
| 20 | − | store, or a branch in the repository ([Git](/architecture/git/#pull-request-forks)). | |
| 17 | + | A work item belongs to a workspace, not to a repository | |
| 18 | + | ([Work items](/guides/work-items/)). `work_items` holds them, numbered per | |
| 19 | + | workspace, with no repository of their own. `work_item_repos` links each | |
| 20 | + | to any number of the workspace's repositories, one row per repository, in | |
| 21 | + | a role: | |
| 21 | 22 | ||
| 23 | + | | Role | Means | | |
| 24 | + | | --- | --- | | |
| 25 | + | | `origin` | The repository it was filed in, if any. For a work item that was an issue, the row keeps the old number as `legacy_number`. | | |
| 26 | + | | `target` | A repository the work is meant to land in. | | |
| 27 | + | | `touched` | A repository where a pull request or commit for it landed or is in progress, added by `work` itself. | | |
| 28 | + | ||
| 29 | + | Each row also keeps the repository's `owner/name`, so a deleted | |
| 30 | + | repository still reads, and when it landed. | |
| 31 | + | ||
| 32 | + | Work items and pull requests share one sequence of numbers per workspace | |
| 33 | + | (`work_counters`), so `#12` names exactly one of them in it. Pull requests | |
| 34 | + | still live in their repository and are unique there: a new one takes the | |
| 35 | + | workspace's next number, never at or below a number its repository already | |
| 36 | + | has. Labels and milestones belong to the workspace too, shared by its work | |
| 37 | + | items and pull requests. | |
| 38 | + | ||
| 39 | + | A pull request records where its head is: a fork of its own, `pulls--<id>` | |
| 40 | + | in the git store, or a branch in the repository | |
| 41 | + | ([Git](/architecture/git/#pull-request-forks)). It records the work item it | |
| 42 | + | is for, the ones it closes and the ones it is only part of, by item id. | |
| 43 | + | ||
| 44 | + | `resolve_ref` is the one place that says what `#N` names, for closing, | |
| 45 | + | Markdown, chat and the CLI. In a repository, `#N` is that repository's pull | |
| 46 | + | request N, else the work item filed there as issue N (its | |
| 47 | + | `legacy_number`), else the workspace's work item N, else pull request N in | |
| 48 | + | another of the workspace's repositories. `owner/name#N` reads as it would | |
| 49 | + | in that repository, and `workspace#N` names another workspace's. | |
| 50 | + | ||
| 51 | + | Who can see and change a work item is `item_role` | |
| 52 | + | ([Identity](/architecture/identity/)). | |
| 53 | + | ||
| 22 | 54 | `work` reads every push from its event queue. A push to a pull request's | |
| 23 | 55 | head updates it: the new head, the files it changes, whether it is behind | |
| 24 | 56 | the base, and which other open pull requests change the same files, the | |
| 25 | 57 | overlap shown on each. | |
| 26 | 58 | ||
| 27 | − | When a pull request merges, its issue closes and records which pull | |
| 28 | − | request resolved it, and the issue's other open pull requests close as | |
| 29 | − | superseded ([How g1t works](/concepts/overview/#several-pull-requests-for-one-issue)). | |
| 59 | + | When a pull request merges into the default branch, or a commit pushed | |
| 60 | + | there says `Closes #N` (or `Fixes`, `Resolves`), `work` marks that | |
| 61 | + | repository as landed on each work item it names, and records a resolution: | |
| 62 | + | the repository, and the pull request or commit. The work item closes when | |
| 63 | + | it has no target, or once every target has landed. `Part of #N` (or | |
| 64 | + | `Refs #N`) links the pull request or commit, and its repository as | |
| 65 | + | touched, without landing anything. References reach every repository of | |
| 66 | + | the same workspace; a work item in another workspace is never closed. The | |
| 67 | + | work item's other open pull requests in that repository close as | |
| 68 | + | superseded ([How g1t works](/concepts/overview/#several-pull-requests-for-one-work-item)). | |
| 69 | + | ||
| 70 | + | Work items were issues, one repository's each, until a migration moved | |
| 71 | + | them into their workspaces: numbered above every number the workspace's | |
| 72 | + | repositories had used, with their repository as origin, and labels and | |
| 73 | + | milestones merged into the workspace's. A job on `work`'s cron | |
| 74 | + | (`work_migration.rs`) assigned the numbers and announced the mapping once, | |
| 75 | + | as `work.migrated`, for the other services to rewrite what they keep. Old | |
| 76 | + | `/<owner>/<repo>/issues/<n>` links and `#N` references resolve through | |
| 77 | + | `legacy_number` ([Issues became work | |
| 78 | + | items](/about/issues-became-work-items/)). | |
| 30 | 79 | ||
| 31 | 80 | ## Coordination | |
| 32 | 81 | ||
| 33 | 82 | Many agents and people can work on one repository at once. `work` keeps | |
| 34 | − | what lets them see each other, around the issue, which is the unit of | |
| 83 | + | what lets them see each other, around the work item, which is the unit of | |
| 35 | 84 | work (`services/work/src/coordination/`): | |
| 36 | 85 | ||
| 37 | 86 | | Table | Holds | Module | | |
| 38 | 87 | | --- | --- | --- | | |
| 39 | − | | `sessions` | One run of someone's own harness (`claude_code`, `codex`, `cursor`, `copilot` or `other`), attached to an issue, a pull request and a branch | `sessions.rs` | | |
| 88 | + | | `sessions` | One run of someone's own harness (`claude_code`, `codex`, `cursor`, `copilot` or `other`), recorded in the repository it is checked out in and attached to a work item of its workspace, a pull request and a branch | `sessions.rs` | | |
| 40 | 89 | | `session_entries` | What a session recorded: prompts, reasoning, tool calls, notes, each with an idempotency `key` | `sessions.rs` | | |
| 41 | 90 | | `claims` | An advisory, expiring "I'm working on #12" | `claims.rs` | | |
| 42 | − | | Issues' `blocked_by` | The issues that have to land first, refused if it would make a cycle | `dependencies.rs` | | |
| 91 | + | | Work items' `blocked_by` | The work items that have to land first, refused if it would make a cycle | `dependencies.rs` | | |
| 43 | 92 | | `overlap_pairs` | Pairs of open pull requests changing the same files, announced once per pair | `overlaps.rs` | | |
| 44 | 93 | ||
| 45 | 94 | <Diagram name="coordination" /> | |
| 46 | 95 | ||
| 47 | 96 | Three choices shape it: | |
| 48 | 97 | ||
| 49 | − | - **Nothing is a lock.** A claim is advice: anyone may claim an issue | |
| 98 | + | - **Nothing is a lock.** A claim is advice: anyone may claim a work item | |
| 50 | 99 | someone else holds, is told about them, and decides. Nothing is ever | |
| 51 | 100 | refused because of a claim (step 9 in the diagram). | |
| 52 | 101 | - **Nothing waits on a harness.** No cron sweeps for quiet sessions or | |
| ⋯ | |||
| 59 | 108 | every time without checking first, and a retry after a lost answer does | |
| 60 | 109 | no harm. | |
| 61 | 110 | ||
| 62 | − | `get_work` gathers an issue's whole context in one call (`context.rs`): the | |
| 63 | − | issue, its definition of done, the required checks, claims, sessions, | |
| 111 | + | `get_work` gathers a work item's whole context in one call (`context.rs`): | |
| 112 | + | the work item, its repositories with their roles, what landed where and | |
| 113 | + | which targets are still missing, suggested targets (each with why), its | |
| 114 | + | definition of done, the required checks, claims, sessions, | |
| 64 | 115 | pull requests with their checks, overlaps and place in the queue, what it | |
| 65 | 116 | is blocked by and blocks, its decision records, and its latest | |
| 66 | 117 | coordination events. A session's entries on a pull request are what | |
| ⋯ | |||
| 147 | 198 | on `merge_group` like any queued state and never land. What is left is | |
| 148 | 199 | reported as the `suspects`. | |
| 149 | 200 | - **Told everywhere.** The answer goes on the pull request's and the | |
| 150 | − | issue's timelines, into the pull request's session, as a decision record | |
| 201 | + | work item's timelines, into the pull request's session, as a decision record | |
| 151 | 202 | (`integration_failure`, confidence `tested`, in `decisions`), and as the | |
| 152 | 203 | `integration.failed` event. A passing combination is recorded as | |
| 153 | 204 | `integration.passed`. | |
| ⋯ | |||
| 169 | 220 | ||
| 170 | 221 | ## Events it publishes and reads | |
| 171 | 222 | ||
| 172 | − | `work` publishes what happens to issues, pull requests, comments, checks | |
| 173 | − | and the queue (`issue.*`, `pull.*`, `comment.*`, `status.created`, | |
| 223 | + | `work` publishes what happens to work items, pull requests, comments, checks | |
| 224 | + | and the queue (`work_item.*`, `pull.*`, `comment.*`, `status.created`, | |
| 174 | 225 | `queue.changed` and the like), and the coordination events: | |
| 175 | 226 | `session.started`, `session.ended`, `work.claimed`, `work.released`, | |
| 176 | 227 | `work.claim_expired`, `work.handoff_requested`, `dependency.changed`, | |
| 20 | 20 | ## Forks | |
| 21 | 21 | ||
| 22 | 22 | A fork is an ordinary repository of the workspace it is in. It has its own | |
| 23 | − | access, settings, rules, issues, pull requests, workflows and project. What | |
| 23 | + | access, settings, rules, pull requests, workflows and project. What | |
| 24 | 24 | it shares with its parent is where it came from: it can be synced from the | |
| 25 | 25 | parent and can open pull requests into it. | |
| 26 | 26 | ||
| ⋯ | |||
| 28 | 28 | ||
| 29 | 29 | Forking copies the parent's **code** (its default branch, or every branch | |
| 30 | 30 | and tag), and the fork's project starts with the **description** of the | |
| 31 | − | parent's project. Nothing else comes with it: no issues or | |
| 31 | + | parent's project. Nothing else comes with it: no work items or | |
| 32 | 32 | pull requests, settings, rulesets, secrets, variables, webhooks, | |
| 33 | 33 | environments, deployments or releases. The fork starts with its own | |
| 34 | 34 | defaults, and with two things off: | |
| ⋯ | |||
| 37 | 37 | who manages its settings turns them on in **Settings → Actions**. Code you | |
| 38 | 38 | copied should not start running on your account, with your secrets and | |
| 39 | 39 | your minutes, just because you copied it. | |
| 40 | − | - **Issues.** A fork usually exists to change code and propose it back; | |
| 41 | − | the conversation stays on the parent. Turn them on in the fork's settings | |
| 42 | − | if it becomes a project of its own. | |
| 40 | + | - **Work items** filed in it. A fork usually exists to change code and | |
| 41 | + | propose it back; the conversation stays on the parent's | |
| 42 | + | [work items](/guides/work-items/). Turn them on in the | |
| 43 | + | fork's settings if it becomes a project of its own. | |
| 43 | 44 | ||
| 44 | 45 | Deployments stay off until the fork's own project is set up. | |
| 45 | 46 | ||
| ⋯ | |||
| 108 | 109 | | Is archived | Stay forks; syncing from it still works. | | |
| 109 | 110 | ||
| 110 | 111 | A detached fork keeps its code, settings and pull requests, and its | |
| 111 | − | workflows and issues stay off unless someone had turned them on. It can no longer be | |
| 112 | + | workflows and work items stay off unless someone had turned them on. It can no longer be | |
| 112 | 113 | synced, and it cannot be attached again. | |
| 113 | 114 | ||
| 114 | 115 | ## Working copies for pull requests | |
| ⋯ | |||
| 205 | 206 | git push origin my-change | |
| 206 | 207 | curl -X POST https://api.g1t.sh/repos/<workspace>/<repo>/pulls \ | |
| 207 | 208 | -H "Authorization: Bearer $G1T_TOKEN" -H "Content-Type: application/json" \ | |
| 208 | − | -d '{"branch": "my-change", "title": "My change", "issue": 12}' | |
| 209 | + | -d '{"branch": "my-change", "title": "My change", "item": 12}' | |
| 209 | 210 | ``` | |
| 210 | 211 | ||
| 211 | 212 | A branch can have one open pull request at a time. Pushing to the branch | |
| 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 | |
| 14 | 14 | ||
| 15 | 15 | | Role | For | | |
| 16 | 16 | | --- | --- | | |
| 17 | − | | **Read** | Read and clone; open issues and pull requests, and comment. | | |
| 18 | − | | **Triage** | Read, and manage issues and pull requests: apply labels and milestones, assign, close. | | |
| 17 | + | | **Read** | Read and clone; open work items and pull requests, and comment. | | |
| 18 | + | | **Triage** | Read, and manage work items and pull requests: apply labels and milestones, assign, link repositories, close. | | |
| 19 | 19 | | **Write** | Triage, and push, merge, manage labels and milestones, and see security alerts. | | |
| 20 | 20 | | **Maintain** | Write, and manage the repository's settings and topics. | | |
| 21 | 21 | | **Admin** | Everything: branch protection and rulesets, webhooks, secrets, deployments, security settings, who has access, and the repository's name, visibility and archiving. | | |
| ⋯ | |||
| 26 | 26 | ||
| 27 | 27 | | | Read | Triage | Write | Maintain | Admin | | |
| 28 | 28 | | --- | --- | --- | --- | --- | --- | | |
| 29 | − | | See code, issues and pull requests; clone and fetch | Yes | Yes | Yes | Yes | Yes | | |
| 30 | − | | Open issues and pull requests, and comment | Yes | Yes | Yes | Yes | Yes | | |
| 31 | − | | Apply labels and milestones; assign, close and reopen issues and pull requests | | Yes | Yes | Yes | Yes | | |
| 29 | + | | See code, work items and pull requests; clone and fetch | Yes | Yes | Yes | Yes | Yes | | |
| 30 | + | | Open work items and pull requests, and comment | Yes | Yes | Yes | Yes | Yes | | |
| 31 | + | | Apply labels and milestones; assign, close and reopen work items and pull requests; link repositories to work items | | Yes | Yes | Yes | Yes | | |
| 32 | 32 | | Push to branches that are not protected | | | Yes | Yes | Yes | | |
| 33 | 33 | | Merge pull requests and use the merge queue | | | Yes | Yes | Yes | | |
| 34 | 34 | | Create, edit and delete labels and milestones | | | Yes | Yes | Yes | | |
| ⋯ | |||
| 55 | 55 | ||
| 56 | 56 | Some things work a little differently on g1t: | |
| 57 | 57 | ||
| 58 | − | - Whoever opened an issue or pull request can still edit, label and close | |
| 58 | + | - Whoever opened a work item or pull request can still edit, label and close | |
| 59 | 59 | their own, whatever their role. | |
| 60 | 60 | - A [protected branch](/guides/git/#protected-branches) takes no pushes | |
| 61 | 61 | from anyone, Maintain and Admin included. To let a role push, list it as | |
| 62 | 62 | a bypass actor of a [ruleset](/guides/rules/) instead. | |
| 63 | − | - Applying a label the repository does not have yet creates it, for | |
| 63 | + | - Applying a label the workspace does not have yet creates it, for | |
| 64 | 64 | someone with Write. | |
| 65 | 65 | ||
| 66 | 66 | Read and Triage cannot start anything that spends compute: workflows and | |
| ⋯ | |||
| 110 | 110 | [rules for tokens](/guides/authentication/#a-workspaces-rules-for-tokens) | |
| 111 | 111 | keep it out. | |
| 112 | 112 | ||
| 113 | + | ### Work items | |
| 114 | + | ||
| 115 | + | [Work items](/guides/work-items/) belong to the workspace, not to one | |
| 116 | + | repository, and so do its labels and milestones. | |
| 117 | + | ||
| 118 | + | - The workspace's members see every work item. | |
| 119 | + | - Anyone who can read a work item's origin repository, the one it was | |
| 120 | + | filed in, sees it. Work items filed in a public repository are public, | |
| 121 | + | and anyone who can take part there can file one. | |
| 122 | + | - A work item with no origin is seen only by members. | |
| 123 | + | ||
| 124 | + | Your role on a work item is the higher of your role through the | |
| 125 | + | workspace (an owner has Admin, a member the base permission) and your role | |
| 126 | + | on its origin repository. Creating, editing and deleting the workspace's | |
| 127 | + | labels and milestones takes Write through the workspace. | |
| 128 | + | ||
| 113 | 129 | ### Private repositories | |
| 114 | 130 | ||
| 115 | 131 | Someone without at least Read on a private repository cannot tell it | |
| 29 | 29 | ||
| 30 | 30 | | On GitHub | On g1t | | |
| 31 | 31 | | --- | --- | | |
| 32 | − | | `on:` `push` (branches, tags, paths), `pull_request`, `pull_request_target`, `issues`, `issue_comment`, `pull_request_review`, `schedule`, `workflow_dispatch`, `workflow_run`, `merge_group`, `create`, `delete`, `repository_dispatch`, `release`, `deployment`, `deployment_status` | The same, from g1t's own pushes, pull requests, issues, comments, [releases](#releases), [deployments](#deployments) and [merge queue](/guides/merge-queue/). `create` starts on each new branch or tag, at its commit; `delete` on each branch or tag a push deletes, on the default branch's latest commit, with `github.event.ref` and `github.event.ref_type` naming what went. As on GitHub, neither takes `branches` or `tags` filters: a workflow on them runs for every branch and tag. `repository_dispatch` starts on [a dispatch event](#repository-dispatch). | | |
| 32 | + | | `on:` `push` (branches, tags, paths), `pull_request`, `pull_request_target`, `issues`, `issue_comment`, `pull_request_review`, `schedule`, `workflow_dispatch`, `workflow_run`, `merge_group`, `create`, `delete`, `repository_dispatch`, `release`, `deployment`, `deployment_status` | The same, from g1t's own pushes, pull requests, [work items](/guides/work-items/) linked to the repository, comments, [releases](#releases), [deployments](#deployments) and [merge queue](/guides/merge-queue/). `issues` is `work_item` on g1t, since issues became work items. `create` starts on each new branch or tag, at its commit; `delete` on each branch or tag a push deletes, on the default branch's latest commit, with `github.event.ref` and `github.event.ref_type` naming what went. As on GitHub, neither takes `branches` or `tags` filters: a workflow on them runs for every branch and tag. `repository_dispatch` starts on [a dispatch event](#repository-dispatch). | | |
| 33 | 33 | | `jobs`, `needs`, `if`, `outputs`, `env`, `defaults`, `timeout-minutes`, `continue-on-error` | The same. | | |
| 34 | 34 | | `timeout-minutes` and `continue-on-error` on a step | The same, for `run:` and `uses:` steps alike. A `uses:` step's action is stopped at its limit, with every process it started; a step inside a composite action stops at its own limit or the `uses:` step's, whichever comes first. A step stopped this way fails, unless `continue-on-error` lets the job go on. | | |
| 35 | 35 | | `strategy.matrix` with `include` and `exclude`, `fail-fast`, `max-parallel`, a matrix from `fromJSON(needs.…)` | The same. | | |
| ⋯ | |||
| 77 | 77 | - **`on: label`, and some activity types.** Creating, editing or deleting | |
| 78 | 78 | a label starts no workflows yet, and the workflow's page says so. Nor do | |
| 79 | 79 | the `pull_request` types `unassigned`, `locked` and `unlocked`, `edited` | |
| 80 | − | for a new title or description, or the `issues` types `unassigned`, | |
| 80 | + | for a new title or description, or the `work_item` types `unassigned`, | |
| 81 | 81 | `locked`, `unlocked`, `pinned` and `unpinned`. | |
| 82 | 82 | - **Background steps.** A step with `background: true`, or a `wait`, | |
| 83 | 83 | `wait-all`, `cancel` or `parallel` step, is refused: g1t does not run | |
| ⋯ | |||
| 543 | 543 | env: | |
| 544 | 544 | TOKEN: ${{ github.token }} | |
| 545 | 545 | run: | | |
| 546 | − | curl -fsS -X POST "$GITHUB_API_URL/repos/$GITHUB_REPOSITORY/issues/${{ github.event.number }}/comments" \ | |
| 546 | + | curl -fsS -X POST "$GITHUB_API_URL/repos/$GITHUB_REPOSITORY/pulls/${{ github.event.number }}/comments" \ | |
| 547 | 547 | -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ | |
| 548 | 548 | -d '{"body": "Built."}' | |
| 549 | 549 | ``` | |
| ⋯ | |||
| 1580 | 1580 | `ready_for_review`, `labeled`, `unlabeled`, `milestoned`, `demilestoned`, | |
| 1581 | 1581 | `assigned`, `review_requested` and `closed`, and `edited` when the branch | |
| 1582 | 1582 | a pull request merges into changes; `issue_comment` workflows on | |
| 1583 | − | `created`, `edited` (with `github.event.changes.body.from`) and `deleted`; `issues` workflows on `assigned`, `labeled`, `unlabeled`, `milestoned` and | |
| 1583 | + | `created`, `edited` (with `github.event.changes.body.from`) and `deleted`; `work_item` workflows on `assigned`, `labeled`, `unlabeled`, `milestoned` and | |
| 1584 | 1584 | `demilestoned` too. List them under `types:` to run on them. For | |
| 1585 | 1585 | `labeled` and `unlabeled`, `github.event.label` names the label; for | |
| 1586 | 1586 | `assigned`, `github.event.assignee` names who was assigned. Assigning | |
| ⋯ | |||
| 1646 | 1646 | `github.event`, and the file at `GITHUB_EVENT_PATH`, hold the webhook | |
| 1647 | 1647 | payload GitHub would send for the event, with the same keys and types. | |
| 1648 | 1648 | ||
| 1649 | − | - **Ids are numbers.** `repository.id`, `pull_request.id`, `issue.id`, | |
| 1649 | + | - **Ids are numbers.** `repository.id`, `pull_request.id`, `work_item.id`, | |
| 1650 | 1650 | `review.id`, `sender.id`, every `user.id` and `owner.id` are whole | |
| 1651 | 1651 | numbers, the same for an object wherever it appears and below 2^53, so | |
| 1652 | 1652 | JavaScript reads them exactly. `node_id` is g1t's own id, such as | |
| ⋯ | |||
| 1659 | 1659 | `release.id`, `deployment.id`, `deployment_status.id`, | |
| 1660 | 1660 | `workflow_run.id` and `workflow_run.workflow_id` are g1t's ids | |
| 1661 | 1661 | (`cmt_…`, `rel_…`, `run_…`, `wfl_…`), so you can pass them straight | |
| 1662 | − | back, as in `PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}` | |
| 1663 | − | or `run-id: ${{ github.event.workflow_run.id }}`. | |
| 1662 | + | back to the [API](/reference/api/), or as | |
| 1663 | + | `run-id: ${{ github.event.workflow_run.id }}`. | |
| 1664 | 1664 | - **`repository.fork`** is true in a [fork](/concepts/forks/), and | |
| 1665 | 1665 | `repository.parent` names the repository it was forked from (its | |
| 1666 | 1666 | `full_name`, `name`, `owner` and `html_url`) when the reader may see it. | |
| ⋯ | |||
| 1689 | 1689 | with their `ref`, `sha` and `repo` (`id`, `url`, `name`). As on | |
| 1690 | 1690 | GitHub, a pull request from a fork is not listed. | |
| 1691 | 1691 | ||
| 1692 | − | Labels on `issue`, `pull_request` and a `labeled` event's `label` have | |
| 1693 | − | their `id`, `name`, `color` and `description` as the repository has | |
| 1694 | − | them, and `default`, which is true for the labels a repository starts | |
| 1695 | − | with. | |
| 1692 | + | Labels on `work_item`, `pull_request` and a `labeled` event's `label` have | |
| 1693 | + | their `id`, `name`, `color` and `description` as the workspace has | |
| 1694 | + | them, and `default`, which is true for the default labels. | |
| 1696 | 1695 | ||
| 1697 | 1696 | ## Checks | |
| 1698 | 1697 | ||
| ⋯ | |||
| 1788 | 1787 | - It **stops working when the job ends**, however it ends. | |
| 1789 | 1788 | - Everything it changes is in the [audit log](/guides/audit-log/) as that | |
| 1790 | 1789 | job's, under its run. | |
| 1791 | − | - What it changes **starts no workflows**: a push, a pull request, an issue | |
| 1790 | + | - What it changes **starts no workflows**: a push, a pull request, a work item | |
| 1792 | 1791 | or a comment made with it runs nothing, so a workflow cannot set itself | |
| 1793 | 1792 | off. `workflow_dispatch` and [`repository_dispatch`](#repository-dispatch) | |
| 1794 | 1793 | are the exceptions, for a workflow that means to start another. | |
| ⋯ | |||
| 1816 | 1815 | | --- | --- | --- | | |
| 1817 | 1816 | | `contents` | Clone and fetch with git, read the repository | Push, publish releases | | |
| 1818 | 1817 | | `pull-requests` | Read pull requests | Open, review, close and merge them | | |
| 1819 | − | | `issues` | Read issues | Open, edit, comment on and close them | | |
| 1818 | + | | `issues` | Read the work items linked to the repository | Open, edit, comment on and close them | | |
| 1820 | 1819 | | `actions` | Read workflows, runs and logs | Run, cancel and re-run them | | |
| 1821 | 1820 | | `checks`, `statuses` | Read statuses and check runs | Report them | | |
| 1822 | 1821 | | `deployments`, `pages` | Read deployments | Report them | | |
| 1 | 1 | --- | |
| 2 | 2 | title: AI providers | |
| 3 | − | description: Choose the models g1t works with in your workspace. Use a frontier lab or a model platform, or a model you host yourself, on your own keys. Ask, @g1t in Chat and sessions on issues answer with them. | |
| 3 | + | description: Choose the models g1t works with in your workspace. Use a frontier lab or a model platform, or a model you host yourself, on your own keys. Ask, @g1t in Chat and sessions on work items answer with them. | |
| 4 | 4 | --- | |
| 5 | 5 | ||
| 6 | 6 | **AI**, at `g1t.sh/<workspace>/-/ai`, is where a workspace chooses the | |
| ⋯ | |||
| 17 | 17 | ||
| 18 | 18 | - **[Ask g1t](/guides/ask/)**, in the top bar, and **@g1t in Chat** | |
| 19 | 19 | answer with the provider and model chosen under **Ask g1t**. | |
| 20 | − | - **Sessions on issues** start on the workspace's Anthropic provider. See | |
| 20 | + | - **Sessions on work items** start on the workspace's Anthropic provider. See | |
| 21 | 21 | [Start a session on your Anthropic account](/guides/sessions/#start-a-session-on-your-anthropic-account). | |
| 22 | 22 | ||
| 23 | 23 | Only workspace owners add, test, change and remove providers, and choose | |
| ⋯ | |||
| 88 | 88 | ||
| 89 | 89 | ### Anthropic Console workspace | |
| 90 | 90 | ||
| 91 | − | Sessions on issues run on the Anthropic provider's account, and the | |
| 91 | + | Sessions on work items run on the Anthropic provider's account, and the | |
| 92 | 92 | Anthropic Console shows each one in the Console workspace its key belongs | |
| 93 | 93 | to. A session does not say which workspace that is, so if the key is not | |
| 94 | 94 | in the account's Default workspace, tell g1t: paste any Console address | |
| 191 | 191 | | Image, video, audio, file | `/image`, `/video`, `/audio`, `/file` | `![]()`, links | | |
| 192 | 192 | | Diagram | `/diagram` or `/mermaid` | ` ```mermaid ` | | |
| 193 | 193 | | Math | `/math` or `/latex` | `$$ … $$` | | |
| 194 | − | | Embed from g1t | `/embed`, then the address of an issue, pull request, channel, project or artifact | a link | | |
| 194 | + | | Embed from g1t | `/embed`, then the address of a work item, pull request, channel, project or artifact | a link | | |
| 195 | 195 | | Date | `/date` | the date | | |
| 196 | 196 | | Cite code | `/cite`: a repository, a path, and what there the doc describes | a link to the file | | |
| 197 | 197 |
| 4 | 4 | --- | |
| 5 | 5 | ||
| 6 | 6 | **Ask**, in the top bar, opens a conversation with g1t beside the page | |
| 7 | − | you are on. Ask about the issue you are reading, the pull request you are | |
| 7 | + | you are on. Ask about the work item you are reading, the pull request you are | |
| 8 | 8 | reviewing, or anything else about your work, and the answer streams in as | |
| 9 | 9 | it is written. | |
| 10 | 10 | ||
| ⋯ | |||
| 47 | 47 | ||
| 48 | 48 | | The question | Auto answers with | | |
| 49 | 49 | | --- | --- | | |
| 50 | − | | A lookup: who has an issue, a link, how many pull requests are open | The provider's newest fast model: Haiku, a `mini` or `flash` model, an `instant` one | | |
| 50 | + | | A lookup: who has a work item, a link, how many pull requests are open | The provider's newest fast model: Haiku, a `mini` or `flash` model, an `instant` one | | |
| 51 | 51 | | One that needs several reads or reasoning: why or how something happened, what shipped, a day or a week summed up, a failure to diagnose, work to plan; a long question, several at once, or a long conversation | Its newest standard model: Sonnet, GPT, Gemini Pro, a `versatile` or `large` one | | |
| 52 | 52 | ||
| 53 | 53 | Auto tells models apart by the words in their names, from the list the | |
| ⋯ | |||
| 69 | 69 | ||
| 70 | 70 | Ask reads g1t to answer: whatever you can read, and nothing more. It uses | |
| 71 | 71 | the same tools the [g1t MCP server](/reference/mcp/) gives any agent, run | |
| 72 | − | as you: repositories and their files and commits, issues, pull requests | |
| 72 | + | as you: repositories and their files and commits, work items, pull requests | |
| 73 | 73 | and their changes, workflow runs and their logs, deployments, releases, | |
| 74 | 74 | production telemetry, and what happened across your workspace. Every read | |
| 75 | 75 | goes through the same permission checks as your own, so it never sees a | |
| 76 | − | repository, issue or log you could not open yourself. | |
| 76 | + | repository, work item or log you could not open yourself. | |
| 77 | 77 | ||
| 78 | 78 | Each question asked from the panel is sent with a short note saying that | |
| 79 | 79 | this is Ask in your workspace and which page you are on (a question | |
| 80 | − | written in Chat says you are in Chat): the repository, and the issue or pull | |
| 81 | − | request number, when there is one. On an issue or a pull request, g1t also | |
| 80 | + | written in Chat says you are in Chat): the repository, and the work item or | |
| 81 | + | pull request number, when there is one. On a work item or a pull request, | |
| 82 | + | g1t also | |
| 82 | 83 | reads its title, state and description, as you can see them, and sends | |
| 83 | 84 | those along, so you can ask "what is left to do here?" without pasting | |
| 84 | 85 | anything. | |
| ⋯ | |||
| 89 | 90 | browser. Anything that would change g1t is refused, whatever your role. | |
| 90 | 91 | ||
| 91 | 92 | Each question is also sent with which page you are on and today's date. On | |
| 92 | − | an issue or a pull request, g1t sends its title, state and description, so | |
| 93 | + | a work item or a pull request, g1t sends its title, state and description, so | |
| 93 | 94 | you can ask "what is left to do here?" without pasting anything. Some | |
| 94 | 95 | questions it answers well: | |
| 95 | 96 | ||
| ⋯ | |||
| 148 | 149 | Ask does not do the work itself: it does not write code or change | |
| 149 | 150 | anything. g1t coordinates the work, and a session in your own harness does | |
| 150 | 151 | it. When you ask for work to be done, such as planning a change, fixing a | |
| 151 | − | bug or implementing an issue, Ask reads the issue the work belongs to, | |
| 152 | − | checks whether a session already holds it, and proposes a session: a card | |
| 153 | − | under the answer that names the issue (or a new one it would open) and | |
| 152 | + | bug or implementing a work item, Ask reads the work item the work belongs | |
| 153 | + | to, checks whether a session already holds it, and proposes a session: a | |
| 154 | + | card under the answer that names the work item (or a new one it would | |
| 155 | + | open) and | |
| 154 | 156 | what the session should do (plan, implement or review). | |
| 155 | 157 | ||
| 156 | 158 | Nothing starts until you choose on the card: | |
| ⋯ | |||
| 162 | 164 | your computer with the [g1t plugin](/guides/claude-code-plugin/), with | |
| 163 | 165 | your own skills, settings and subagents. | |
| 164 | 166 | ||
| 165 | − | Either way the session is tied to the issue: it shows on the issue, on the | |
| 166 | − | repository's Work page and on its own session page, with its subagents, and | |
| 167 | − | Ask can tell you where it stands. If a session already holds the issue, Ask | |
| 167 | + | Either way the session is tied to the work item: it shows on the work | |
| 168 | + | item, on the repository's Sessions page and on its own session page, with | |
| 169 | + | its subagents, and Ask can tell you where it stands. If a session already | |
| 170 | + | holds the work item, Ask | |
| 168 | 171 | links it rather than proposing another. | |
| 169 | 172 | ||
| 170 | 173 | ### Building something new | |
| ⋯ | |||
| 179 | 182 | ||
| 180 | 183 | Choosing **Start session** or **Copy Claude Code command**: | |
| 181 | 184 | ||
| 182 | − | 1. Creates the repository as you, with the issue's title as its project's | |
| 185 | + | 1. Creates the repository as you, with the work item's title as its project's | |
| 183 | 186 | description. | |
| 184 | 187 | 2. Turns on its [deployments](/guides/deployments/). This needs the | |
| 185 | 188 | workspace on the g1t plan and the Admin role on the repository, which | |
| 186 | 189 | you have as its creator. If it can't, the card says **Not deployed:** | |
| 187 | 190 | and why, and the session still builds the app. | |
| 188 | − | 3. Opens the issue and starts the session. | |
| 191 | + | 3. Opens the work item, with the new repository as its origin, and starts | |
| 192 | + | the session. | |
| 189 | 193 | ||
| 190 | 194 | The card then shows **Created** with a link to the repository, and **Live | |
| 191 | 195 | once the first version is pushed at** its production address on | |
| 192 | 196 | g1t.page. The session pushes its first working version straight to the | |
| 193 | 197 | default branch, since an empty repository has nothing to open a pull | |
| 194 | − | request against, closes the issue, and watches `g1t deploy list` until | |
| 198 | + | request against, closes the work item, and watches `g1t deploy list` until | |
| 195 | 199 | production is live, ending its report with the address. Every change after | |
| 196 | 200 | that goes through pull requests as usual. Choosing the card again, or Copy | |
| 197 | 201 | after Start, uses the repository it already made. | |
| ⋯ | |||
| 224 | 228 | Ask is your **direct message with @g1t** in [Chat](/guides/chat/#talk-with-g1t). | |
| 225 | 229 | What you ask in the panel is posted there, and g1t's answer is written | |
| 226 | 230 | there as it streams, so it shows in both places at once: start a question | |
| 227 | − | on an issue page, and read the answer later in Chat, on your phone, or | |
| 231 | + | on a work item's page, and read the answer later in Chat, on your phone, or | |
| 228 | 232 | in the desktop app. **Open in Chat** at the top of the panel takes you to | |
| 229 | 233 | it. Nobody else can read it, and it stays until you delete it or | |
| 230 | 234 | [clear it](#clear-the-conversation). | |
| ⋯ | |||
| 244 | 248 | and model that wrote it, with **Auto** when Auto chose the model. | |
| 245 | 249 | ||
| 246 | 250 | Answers are Markdown: code is highlighted with its language and a Copy | |
| 247 | − | button, tables scroll within the answer, and issues, pull requests and | |
| 248 | − | commits (`acme/web#12`, a link to one, a commit hash) show as chips that | |
| 251 | + | button, tables scroll within the answer, and work items, pull requests and | |
| 252 | + | commits (`#12`, `acme/web#12`, a link to one, a commit hash) show as chips that | |
| 249 | 253 | open their title and state when you hover over them. Links to | |
| 250 | 254 | [artifacts](/guides/artifacts/) show their card. Pictures show only from | |
| 251 | 255 | g1t itself; any other picture is a link. | |
| ⋯ | |||
| 274 | 278 | | --- | --- | | |
| 275 | 279 | | Your questions, and the page each was asked from | The direct message itself, empty, so Ask and Chat open it as before | | |
| 276 | 280 | | g1t's answers, with their steps, sources and proposed sessions | Chat's daily count of messages and bytes for the workspace, which has no text and no names in it and is kept for billing | | |
| 277 | − | | Thread replies, reactions, "New conversation" marks, and deleted messages' empty places | Issues, pull requests and sessions you started from an answer: they are your workspace's, not the conversation's | | |
| 281 | + | | Thread replies, reactions, "New conversation" marks, and deleted messages' empty places | Work items, pull requests and sessions you started from an answer: they are your workspace's, not the conversation's | | |
| 278 | 282 | | Your read mark and unread count for it | What your AI provider was sent to answer: it went to the provider, under your workspace's agreement with them | | |
| 279 | 283 | | The notifications its answers sent you, in g1t's notifications panel | Browser and phone notifications already shown on a device | | |
| 280 | 284 | ||
| 6 | 6 | Every workspace keeps an audit log. It records: | |
| 7 | 7 | ||
| 8 | 8 | - **Every change people and workspace tokens make** through the API, the | |
| 9 | − | MCP server and git: opening and closing issues, comments, merges, | |
| 9 | + | MCP server and git: opening and closing work items, comments, merges, | |
| 10 | 10 | settings, pushes. Reads by people are not recorded. A workflow job's | |
| 11 | 11 | [`G1T_TOKEN`](/guides/actions/#the-jobs-token) is recorded as that job's, | |
| 12 | 12 | under its run. | |
| ⋯ | |||
| 76 | 76 | | Actor | Who did it: a person, or the workspace for its own tokens and deploy keys. | | |
| 77 | 77 | | Run | The workflow run whose job's token did it, as `workflow_job`. | | |
| 78 | 78 | | Credential | The id of the token used: on the API, the MCP server or git, or on g1t.sh by a token [used on the website](/guides/authentication/#use-a-token-on-the-website). Empty for a person signed in on g1t.sh. | | |
| 79 | − | | Action | The API or MCP operation, such as `create_issue`, or `git.push` and `git.fetch`. | | |
| 80 | − | | Target | The repository, the issue or pull request number, and for git the refs it moved. | | |
| 79 | + | | Action | The API or MCP operation, such as `open_work_item`, or `git.push` and `git.fetch`. | | |
| 80 | + | | Target | The repository or workspace, the work item or pull request number, and for git the refs it moved. | | |
| 81 | 81 | | Outcome | `allowed` or `denied`. | | |
| 82 | 82 | | Rule | What decided it: a refusal rule, such as `scope:repository`, or `token:repository` for a workflow job's token used on another repository; or, for people, their own access. A push allowed through is `person`, `workspace-token`, `deploy-key` or `agent-token`, after what pushed. A refusal by the repository's own rules is `service` (or `repository` for git). | | |
| 83 | 83 | | Result | `ok`, or the reason it failed. | | |
| 560 | 560 | ||
| 561 | 561 | There is one kind of access token. Every token has: | |
| 562 | 562 | ||
| 563 | − | - **Permissions**: a level for each resource, such as Issues: read and | |
| 563 | + | - **Permissions**: a level for each resource, such as Work: read and | |
| 564 | 564 | write, or Code: read. See [permissions](#permissions). | |
| 565 | 565 | - **A reach**: the workspaces and repositories it works in. See | |
| 566 | 566 | [where a token reaches](#where-a-token-reaches). | |
| ⋯ | |||
| 766 | 766 | ### Permissions | |
| 767 | 767 | ||
| 768 | 768 | A permission is a resource and a level. A higher level includes the lower | |
| 769 | − | ones: Issues: read and write includes reading issues. Each level is one of | |
| 770 | − | g1t's [scopes](#scopes), so Issues: read and write is `issues:write`; the | |
| 769 | + | ones: Work: read and write includes reading work items. Each level is one of | |
| 770 | + | g1t's [scopes](#scopes), so Work: read and write is `work:write`; the | |
| 771 | 771 | API, the MCP server and git check every token by those scopes. | |
| 772 | 772 | ||
| 773 | 773 | Repository permissions apply in every repository the token reaches: | |
| ⋯ | |||
| 778 | 778 | | Code | read, read and write | `code:read`, `code:write` | | |
| 779 | 779 | | Security | read, read and write | `security:read`, `security:write` | | |
| 780 | 780 | | Packages | read, read and write, read, write and delete | `packages:read`, `packages:write`, `packages:delete` | | |
| 781 | − | | Issues | read, read and write | `issues:read`, `issues:write` | | |
| 781 | + | | Work | read, read and write | `work:read`, `work:write` | | |
| 782 | 782 | | Pull requests | read, read and write | `pull_requests:read`, `pull_requests:write` | | |
| 783 | 783 | | Workflows | read, read and write | `workflows:read`, `workflows:write` | | |
| 784 | 784 | | Workflow files | write | `workflow_files:write` | | |
| ⋯ | |||
| 822 | 822 | | No workspace | Your account, and public repositories. | | |
| 823 | 823 | ||
| 824 | 824 | Wherever it does not reach, a token reads public repositories, read-only, | |
| 825 | − | as anyone can; it cannot comment, open issues or push there. While a token | |
| 825 | + | as anyone can; it cannot comment, open work items or push there. While a token | |
| 826 | 826 | made for a workspace is pending, denied or revoked, that is all it does | |
| 827 | 827 | there too. | |
| 828 | 828 | ||
| ⋯ | |||
| 839 | 839 | | Preset | Permissions | | |
| 840 | 840 | | --- | --- | | |
| 841 | 841 | | Read only | Every resource at read except Chat. Changes nothing. | | |
| 842 | − | | Agent | Every resource at read except Self-hosted runners and Chat, Repositories at read and create, and Code, Issues, Pull requests and Notifications at read and write. For a [coding agent](/guides/bring-your-own-agent/): reads everything, creates repositories, works on issues and pull requests, pushes code, and answers your inbox. It cannot change or delete a repository, its settings, branches or releases. No admin level. | | |
| 842 | + | | Agent | Every resource at read except Self-hosted runners and Chat, Repositories at read and create, and Code, Work, Pull requests and Notifications at read and write. For a [coding agent](/guides/bring-your-own-agent/): reads everything, creates repositories, works on work items and pull requests, pushes code, and answers your inbox. It cannot change or delete a repository, its settings, branches or releases. No admin level. | | |
| 843 | 843 | | CI | Repositories: read; Code, Packages, Workflows, Checks and statuses, and Deployments: read and write. Clones and pushes code, pushes and pulls packages, runs workflows, and reports [checks](/guides/checks/) and deployments. | | |
| 844 | 844 | ||
| 845 | 845 | **All** is not a preset that grows: it ticks every permission there is | |
| ⋯ | |||
| 851 | 851 | ## Scopes | |
| 852 | 852 | ||
| 853 | 853 | A scope is a permission's level, written `resource:level`, such as | |
| 854 | − | `issues:write`. A token stores the highest scope of each resource it | |
| 854 | + | `work:write`. A token stores the highest scope of each resource it | |
| 855 | 855 | holds, and every check reads them. A higher level includes the lower ones | |
| 856 | 856 | of the same resource: `repo:admin` includes `repo:write`, which includes | |
| 857 | 857 | `repo:create`, which includes `repo:read`. It never includes another resource: `repo:admin` does not let | |
| ⋯ | |||
| 874 | 874 | | `packages:read` | Pull container images and install private [packages](/guides/packages/). Public ones need no scope. | | |
| 875 | 875 | | `packages:write` | Push container images and publish packages; with the Admin role on a package, change its settings | | |
| 876 | 876 | | `packages:delete` | Delete and restore packages and their versions | | |
| 877 | − | | `issues:read` | Read issues and comments | | |
| 878 | − | | `issues:write` | Open, edit, close and comment on issues | | |
| 877 | + | | `work:read` | Read [work items](/guides/work-items/) and comments | | |
| 878 | + | | `work:write` | Open, edit, link, claim, close and comment on work items | | |
| 879 | 879 | | `pull_requests:read` | Read pull requests, their changes, sessions and merge queues | | |
| 880 | 880 | | `pull_requests:write` | Open, review, close and merge pull requests | | |
| 881 | 881 | | `workflows:read` | Read workflows, runs and logs | | |
| ⋯ | |||
| 979 | 979 | { | |
| 980 | 980 | "error": { | |
| 981 | 981 | "code": "forbidden", | |
| 982 | − | "message": "This access token needs the issues:write scope to use create_issue.", | |
| 983 | − | "needed_scope": "issues:write" | |
| 982 | + | "message": "This access token needs the work:write scope to use open_work_item.", | |
| 983 | + | "needed_scope": "work:write" | |
| 984 | 984 | } | |
| 985 | 985 | } | |
| 986 | 986 | ``` | |
| ⋯ | |||
| 1028 | 1028 | person. | |
| 1029 | 1029 | ||
| 1030 | 1030 | It has the Write role on the workspace's repositories, as a member does: | |
| 1031 | − | it pushes, merges and works on issues and pull requests, within its | |
| 1031 | + | it pushes, merges and works on work items and pull requests, within its | |
| 1032 | 1032 | permissions. Give it **Repositories: admin** to make it an admin of the | |
| 1033 | 1033 | workspace's repositories instead, so it can also manage webhooks, secrets, | |
| 1034 | 1034 | deploy keys and who has access, and manage teams as an owner would. Only an | |
| ⋯ | |||
| 1081 | 1081 | | --- | --- | --- | --- | | |
| 1082 | 1082 | | [`GET /workspaces/{workspace}/personal-access-token-policy`](/reference/api/personal-access-tokens/get-token-policy/) | `workspace` `get_token_policy` | The rules. Members may read them. | `workspace:read` | | |
| 1083 | 1083 | | [`PATCH /workspaces/{workspace}/personal-access-token-policy`](/reference/api/personal-access-tokens/set-token-policy/) | `workspace` `set_token_policy` | Change `allow_tokens_for_this_workspace`, `allow_tokens_for_all_workspaces`, `require_approval`, `max_lifetime_days` (0 for no limit) or `forbid_no_expiry` | `workspace:admin` | | |
| 1084 | − | | [`GET /workspaces/{workspace}/personal-access-tokens`](/reference/api/personal-access-tokens/list-member-tokens/) | `workspace` `list_member_tokens` | The tokens that can reach it, each with its `permissions` (`{"issues": "write"}`), `scopes`, `workspace` (null when made for all of its owner's), `repository_selection`, `repositories` and `status` | `access:read` | | |
| 1084 | + | | [`GET /workspaces/{workspace}/personal-access-tokens`](/reference/api/personal-access-tokens/list-member-tokens/) | `workspace` `list_member_tokens` | The tokens that can reach it, each with its `permissions` (`{"work": "write"}`), `scopes`, `workspace` (null when made for all of its owner's), `repository_selection`, `repositories` and `status` | `access:read` | | |
| 1085 | 1085 | | [`GET /workspaces/{workspace}/personal-access-token-requests`](/reference/api/personal-access-tokens/list-token-requests/) | `workspace` `list_token_requests` | The tokens waiting for approval | `access:read` | | |
| 1086 | 1086 | | [`POST /workspaces/{workspace}/personal-access-token-requests/{id}`](/reference/api/personal-access-tokens/review-token-request/) | `workspace` `review_token_request` | `decision` is `approve` or `deny`, with an optional `reason` | `access:admin` | | |
| 1087 | 1087 | | [`POST /workspaces/{workspace}/personal-access-tokens/{id}`](/reference/api/personal-access-tokens/revoke-member-token/) | `workspace` `revoke_member_token` | Revoke a token in the workspace, with an optional `reason` | `access:admin` | | |
| ⋯ | |||
| 1102 | 1102 | ||
| 1103 | 1103 | An application that asks for no scopes in particular gets the | |
| 1104 | 1104 | [Agent preset](#presets): every `read` scope except `runners:read` and `chat:read`, and `repo:create`, | |
| 1105 | − | `code:write`, `issues:write`, `pull_requests:write` and `notifications:write`. | |
| 1105 | + | `code:write`, `work:write`, `pull_requests:write` and `notifications:write`. | |
| 1106 | 1106 | The scopes are kept when you approve it: an application approved before | |
| 1107 | 1107 | `repo:create` joined the preset gets it only once you add it under | |
| 1108 | 1108 | Connected applications, or sign it in again. | |
| ⋯ | |||
| 1134 | 1134 | - Registration stores nothing. The client id it returns encodes what was | |
| 1135 | 1135 | registered, so it cannot be used to fill g1t with junk. | |
| 1136 | 1136 | - Ask for scopes with `scope` on the authorization request, separated by | |
| 1137 | − | spaces, such as `scope=repo:read issues:write pull_requests:write`. | |
| 1137 | + | spaces, such as `scope=repo:read work:write pull_requests:write`. | |
| 1138 | 1138 | Names g1t does not know are left out. Leave `scope` out for the Agent | |
| 1139 | 1139 | preset. The authorization server's metadata and | |
| 1140 | 1140 | `https://mcp.g1t.sh/.well-known/oauth-protected-resource` list every | |
| ⋯ | |||
| 1297 | 1297 | | | | | |
| 1298 | 1298 | | --- | --- | | |
| 1299 | 1299 | | Your addresses, keys and profile | Removed: your email addresses, two-factor secret and recovery codes, GitHub link, picture, profile and security log, and your notifications and their settings. | | |
| 1300 | − | | What you wrote | Issues, pull requests, comments and reviews keep their place and their words, and show as written by `ghost`. You are taken off issues and pull requests you were assigned to or asked to review. Commits keep the name and address git recorded in them; those made with your [noreply address](#keeping-your-address-private) show as `ghost`. | | |
| 1300 | + | | What you wrote | Work items, pull requests, comments and reviews keep their place and their words, and show as written by `ghost`. You are taken off work items and pull requests you were assigned to or asked to review. Commits keep the name and address git recorded in them; those made with your [noreply address](#keeping-your-address-private) show as `ghost`. | | |
| 1301 | 1301 | | Workspaces you made | Name `ghost` as their creator. | | |
| 1302 | 1302 | | Statements, invoices and audit logs | Kept with your username, for the workspaces they belong to. | | |
| 1303 | 1303 | | Your username | Never given to another account or workspace, so links, mentions and remotes that use it keep meaning what they meant. `ghost` is reserved for this, and nobody can register it. | | |
| 44 | 44 | | Required checks, approvals, being up to date | As the rules covering it ask | As the rules covering it ask; nothing when none cover it | | |
| 45 | 45 | | [Merge queue](/guides/merge-queue/) | Joins it, when a rule requires it | Never; it merges directly | | |
| 46 | 46 | | Catching up | Merges the default branch in | Merges its base in | | |
| 47 | − | | Its issue | Closes when it merges | Stays open | | |
| 47 | + | | Its [work item](/guides/work-items/) | Records the repository as landed when it merges, and closes once every target has | Nothing lands; it stays open | | |
| 48 | 48 | ||
| 49 | 49 | Merging still needs the Write role. Under **Settings → Rules**, **What holds | |
| 50 | 50 | for a branch** shows every rule that covers a branch. |
| 21 | 21 | ||
| 22 | 22 | The agent runs where you run it: on your machine, in your CI, or on a | |
| 23 | 23 | [runner](/guides/self-hosted-runners/) of your own, on your own model | |
| 24 | − | account. g1t runs no agents of its own; it keeps the code, the issues and | |
| 25 | − | pull requests, the checks and the record of what happened. To start one | |
| 26 | − | from g1t instead, see [hand an issue to g1t](#hand-an-issue-to-g1t). | |
| 24 | + | account. g1t runs no agents of its own; it keeps the code, the work items | |
| 25 | + | and pull requests, the checks and the record of what happened. To start | |
| 26 | + | one from g1t instead, see [hand a work item to g1t](#hand-a-work-item-to-g1t). | |
| 27 | 27 | ||
| 28 | 28 | ## Connect your AI client | |
| 29 | 29 | ||
| ⋯ | |||
| 75 | 75 | and an [access token](/guides/authentication/#access-tokens) with | |
| 76 | 76 | `code:write`. | |
| 77 | 77 | ||
| 78 | − | Ask it to list the open issues on a repository, or to work on one, and it | |
| 78 | + | Ask it to list the open work items of a workspace or a repository, or to | |
| 79 | + | work on one, and it | |
| 79 | 80 | will use g1t's tools. It sees only the tools and actions its access allows. | |
| 80 | 81 | ||
| 81 | 82 | ### With a token instead | |
| ⋯ | |||
| 106 | 107 | the agent does is done as you, and shows as you in the | |
| 107 | 108 | [audit log](/guides/audit-log/). | |
| 108 | 109 | ||
| 109 | − | ## How an agent works on an issue | |
| 110 | + | ## How an agent works on a work item | |
| 110 | 111 | ||
| 111 | − | 1. `issue` with `work`, to load everything about it in one call: what | |
| 112 | − | done means, who has claimed it, the pull requests already made for it, | |
| 113 | − | and what it is blocked by. Then `issue` with `claim`, which also says | |
| 114 | − | who else is on it. | |
| 115 | − | 2. `pull_request` with `create` and the issue's number. This opens a draft | |
| 116 | − | pull request and returns the git remote of its [working copy](/concepts/forks/#working-copies-for-pull-requests). | |
| 112 | + | 1. `work_item` with `work`, to load everything about it in one call: what | |
| 113 | + | done means, the repositories it is meant to land in and which have, | |
| 114 | + | who has claimed it, the pull requests already made for it, and what it | |
| 115 | + | is blocked by. Then `work_item` with `claim`, which also says who else | |
| 116 | + | is on it. | |
| 117 | + | 2. `pull_request` with `create` in the repository the change is for, and | |
| 118 | + | the work item's number as `item`. This opens a draft pull request and returns the git remote of its [working copy](/concepts/forks/#working-copies-for-pull-requests). | |
| 117 | 119 | 3. Clone the working copy, make changes, commit and push. | |
| 118 | 120 | 4. `pull_request` with `record_session` as it goes, so people can see its | |
| 119 | 121 | reasoning. | |
| 120 | 122 | 5. `pull_request` with `get`, to check `overlaps`, `behind` and the checks. | |
| 121 | 123 | 6. `pull_request` with `ready` and a summary of what changed and why. | |
| 122 | 124 | ||
| 123 | − | ### Work with no issue yet | |
| 125 | + | ### Work with no work item yet | |
| 124 | 126 | ||
| 125 | − | Most of what an agent is asked starts without an issue, and a question, | |
| 127 | + | Most of what an agent is asked starts without a work item, and a question, | |
| 126 | 128 | a look around or a trivial fix never needs one. Record the session | |
| 127 | 129 | anyway (`session` with `start`), with a `title` saying what it is for: the | |
| 128 | − | team sees it in **Live now** on the project's overview and **Work** page, | |
| 130 | + | team sees it in **Live now** on the project's overview and **Sessions** page, | |
| 129 | 131 | under its pull request or branch. When the work becomes a change others | |
| 130 | − | should know about (a branch to push, a pull request), look for its issue | |
| 131 | − | (`issue` with `list` or `list_claims`) and claim it. If there is none, | |
| 132 | − | `issue` with `claim`, a `title` and no `number` opens one and claims it | |
| 133 | − | in one step, and attaches the session (`session_id`) to it: | |
| 132 | + | should know about (a branch to push, a pull request), look for its work | |
| 133 | + | item (`work_item` with `list` or `list_claims`) and claim it. If there is | |
| 134 | + | none, `work_item` with `claim`, a `title` and no `number` opens one, with | |
| 135 | + | the repository as its origin, and claims it in one step, and attaches the | |
| 136 | + | session (`session_id`) to it: | |
| 134 | 137 | ||
| 135 | 138 | ```json | |
| 136 | − | { "name": "issue", "arguments": { "action": "claim", "repo": "flagon-io/hello", "title": "Preview builds time out on large repositories", "session_id": "ses_01m4b2c3d4e5f6g7h8j9k0m1n2" } } | |
| 139 | + | { "name": "work_item", "arguments": { "action": "claim", "repo": "flagon-io/hello", "title": "Preview builds time out on large repositories", "session_id": "ses_01m4b2c3d4e5f6g7h8j9k0m1n2" } } | |
| 137 | 140 | ``` | |
| 138 | 141 | ||
| 139 | − | See [Work with no issue yet](/guides/sessions/#work-with-no-issue-yet). | |
| 142 | + | See [Work with no work item yet](/guides/sessions/#work-with-no-work-item-yet). | |
| 140 | 143 | ||
| 141 | 144 | The call that starts the pull request: | |
| 142 | 145 | ||
| 143 | 146 | ```json | |
| 144 | − | { "name": "pull_request", "arguments": { "action": "create", "repo": "flagon-io/hello", "issue": 42, "agent": "claude-code" } } | |
| 147 | + | { "name": "pull_request", "arguments": { "action": "create", "repo": "flagon-io/hello", "item": 42, "agent": "claude-code" } } | |
| 145 | 148 | ``` | |
| 146 | 149 | ||
| 147 | 150 | `agent` names the harness, so people can see what made the change. Its | |
| ⋯ | |||
| 181 | 184 | ```md title="AGENTS.md" | |
| 182 | 185 | ## Working on g1t | |
| 183 | 186 | ||
| 184 | − | - Work in a draft pull request (`pull_request` `create` with the issue), | |
| 187 | + | - Work in a draft pull request (`pull_request` `create` with the work | |
| 188 | + | item as `item`), | |
| 185 | 189 | and record your session with `record_session` before each push. | |
| 186 | 190 | - Read `overlaps` and `behind` on `pull_request` `get` before going far. | |
| 187 | 191 | - Say why you made a choice with `pull_request` `record_decision`. | |
| 188 | 192 | ``` | |
| 189 | 193 | ||
| 190 | 194 | An agent with a shell can use the [g1t CLI](/guides/cli/) instead of the | |
| 191 | − | tools, and claim the issue, record its session and hand off with it: the | |
| 195 | + | tools, and claim the work item, record its session and hand off with it: the | |
| 192 | 196 | lines for that are in | |
| 193 | 197 | [other coding agents](/guides/claude-code-plugin/#other-coding-agents). | |
| 194 | 198 | With Claude Code, the [plugin](/guides/claude-code-plugin/) does this for | |
| ⋯ | |||
| 225 | 229 | them with, and its pushes, through the [g1t CLI](/guides/cli/), which | |
| 226 | 230 | must be installed and signed in (`g1t auth login`), and title each | |
| 227 | 231 | session with what its first prompt asked for. They never send what a | |
| 228 | − | tool returned. The plugin also gives Claude the issue's work context when | |
| 229 | − | a session starts (or, with no issue, when to claim or open one), g1t's MCP | |
| 230 | − | server, and commands to claim and hand off issues. See [Claude Code plugin](/guides/claude-code-plugin/) for | |
| 232 | + | tool returned. The plugin also gives Claude the work item's context when | |
| 233 | + | a session starts (or, with no work item, when to claim or open one), g1t's | |
| 234 | + | MCP server, and commands to claim and hand off work items. See [Claude Code plugin](/guides/claude-code-plugin/) for | |
| 231 | 235 | everything it records, and how to opt out. | |
| 232 | 236 | ||
| 233 | 237 | Other agents record a session with the same CLI commands, from their | |
| ⋯ | |||
| 241 | 245 | ||
| 242 | 246 | - `overlaps`: other pull requests in progress that change files this one | |
| 243 | 247 | changes, with the paths. An overlap with a pull request for a different | |
| 244 | − | issue will become a conflict for whichever merges second, so narrow the | |
| 248 | + | work item will become a conflict for whichever merges second, so narrow the | |
| 245 | 249 | change, or say so in the pull request. | |
| 246 | 250 | - `behind`: whether `main` has moved since the pull request was made. If | |
| 247 | 251 | it has, `update_branch` before asking for a merge. | |
| ⋯ | |||
| 250 | 254 | [merge queue](/guides/merge-queue/) hold for an agent's pull request | |
| 251 | 255 | exactly as for a person's. | |
| 252 | 256 | ||
| 253 | − | ## Hand an issue to g1t | |
| 257 | + | ## Hand a work item to g1t | |
| 254 | 258 | ||
| 255 | 259 | g1t runs no model of its own, but it can start a session for you on the | |
| 256 | 260 | workspace's own Anthropic account. Once an owner adds an Anthropic key | |
| 257 | 261 | under [**AI**](/guides/ai/): | |
| 258 | 262 | ||
| 259 | − | - **Assign to g1t** in an issue's sidebar (or `g1t issue edit 12 | |
| 260 | − | --add-assignee g1t`), or mention `@g1t` in a comment on an issue or pull | |
| 261 | − | request, with what you want done. | |
| 262 | − | - **Start a session** on an issue's page, `g1t work dispatch 12`, or the | |
| 263 | + | - **Assign to g1t** in a work item's sidebar (or `g1t work edit 12 | |
| 264 | + | --add-assignee g1t`), or mention `@g1t` in a comment on a work item or | |
| 265 | + | pull request, with what you want done. | |
| 266 | + | - **Start a session** on a work item's page, `g1t work dispatch 12`, or the | |
| 263 | 267 | `session` tool's `dispatch` action, to choose the mode (`plan`, | |
| 264 | 268 | `implement` or `review`). | |
| 265 | 269 | ||
| 266 | 270 | g1t reacts 👀, then starts the session as you, with a token for that | |
| 267 | 271 | repository only that is revoked when the session ends. It installs the | |
| 268 | 272 | g1t CLI, clones the repository and works the way this page describes; its | |
| 269 | − | card shows in the issue's conversation, and Anthropic bills the account | |
| 273 | + | card shows in the work item's conversation, and Anthropic bills the account | |
| 270 | 274 | for it. Without an Anthropic key, `g1t work dispatch` prints a Claude Code | |
| 271 | 275 | command to run yourself instead. See | |
| 272 | 276 | [Assign g1t](/guides/sessions/#assign-g1t-or-ask-it-in-the-thread) and | |
| ⋯ | |||
| 279 | 283 | ||
| 280 | 284 | - **Webhooks.** Register an address for a repository or a whole workspace | |
| 281 | 285 | with the `webhook` tool or in its settings, and choose the events, such | |
| 282 | − | as `issue.labeled`, `issue.assigned`, `comment.created`, | |
| 286 | + | as `work_item.labeled`, `work_item.assigned`, `comment.created`, | |
| 283 | 287 | `checks.completed` or `workflow.completed`. Each delivery is signed. See | |
| 284 | 288 | [webhooks](/guides/webhooks/). | |
| 285 | 289 | - **Workflows.** A workflow in `.g1t/workflows/` can start on `issues` or | |
| ⋯ | |||
| 292 | 296 | ||
| 293 | 297 | ## Reviewing as an agent | |
| 294 | 298 | ||
| 295 | − | An agent can review as well as write. Given an issue with several pull | |
| 299 | + | An agent can review as well as write. Given a work item with several pull | |
| 296 | 300 | requests, it can call `pull_request` with `changes` and `read_session` on | |
| 297 | 301 | each, compare them, and read each one's check results from `get`. It can | |
| 298 | − | leave findings on specific lines with `issue` and `comment`, give a verdict | |
| 302 | + | leave findings on specific lines with `work_item` and `comment`, give a verdict | |
| 299 | 303 | with `pull_request` and `review`, and, with the Write role, `merge` the | |
| 300 | 304 | best one. It cannot approve or request changes on a pull request it opened. | |
| 301 | 305 | ||
| ⋯ | |||
| 338 | 342 | that they are not here yet. A workspace's own token cannot use artifacts: | |
| 339 | 343 | they always belong to a person. | |
| 340 | 344 | ||
| 341 | − | ## Filing issues from another system | |
| 345 | + | ## Filing work items from another system | |
| 342 | 346 | ||
| 343 | − | Anything that holds an access token can open issues: an error tracker, a | |
| 344 | − | monitor, a script. Call the `issue` tool with `create`, or `POST | |
| 345 | − | /repos/{owner}/{name}/issues`, with a title, a description and labels | |
| 346 | − | such as `bug`. Its token needs `issues:write`. The issue is attributed to | |
| 347 | − | the account the token belongs to. | |
| 347 | + | Anything that holds an access token can open work items: an error | |
| 348 | + | tracker, a monitor, a script. Call the `work_item` tool with `create`, or | |
| 349 | + | `POST /workspaces/{workspace}/work`, with a title, a description, labels | |
| 350 | + | such as `bug`, and the `repo` it is about as its origin. Its token needs | |
| 351 | + | `work:write`. The work item is attributed to the account the token | |
| 352 | + | belongs to. | |
| 348 | 353 | ||
| 349 | 354 | ## Tools | |
| 350 | 355 | ||
| 351 | 356 | Each tool is a kind of thing on g1t and takes an `action`, such as `get` | |
| 352 | − | or `create`. Repositories are given as `owner/name`, and issues and pull | |
| 353 | − | requests as the repository and a `number`. | |
| 357 | + | or `create`. Repositories are given as `owner/name`, pull requests as the | |
| 358 | + | repository and a `number`, and work items as the `workspace` and a | |
| 359 | + | `number`. | |
| 354 | 360 | ||
| 355 | 361 | | Tool | What it covers | | |
| 356 | 362 | | --- | --- | | |
| 357 | − | | `search` | Code, repositories, issues, pull requests and people across g1t; a tracker's ticket | | |
| 358 | − | | `repository` | Repositories, their settings, rulesets, branches, labels, milestones and releases | | |
| 359 | − | | `issue` | Issues, labels and comments; an issue's whole context, and claims | | |
| 363 | + | | `search` | Code, repositories, work items, pull requests and people across g1t; a tracker's ticket | | |
| 364 | + | | `repository` | Repositories, their settings, rulesets, branches and releases | | |
| 365 | + | | `work_item` | Work items, their repositories, labels and comments; a work item's whole context, and claims | | |
| 360 | 366 | | `pull_request` | Pull requests: create, record and read sessions, review, merge, the merge queue | | |
| 361 | − | | `session` | Your harness's session: start, update, record, end, get, list; dispatch work on an issue; who else is working | | |
| 367 | + | | `session` | Your harness's session: start, update, record, end, get, list; dispatch work on a work item; who else is working | | |
| 362 | 368 | | `workflow` | Workflow runs and logs, checks, deployments, environments and runners | | |
| 363 | 369 | | `observability` | A project's requests, logs, traces, errors and metrics in production | | |
| 364 | 370 | | `package` | Packages in every registry | | |
| ⋯ | |||
| 367 | 373 | | `webhook` | Webhooks and their deliveries | | |
| 368 | 374 | | `access` | Who has which role on a repository, and deploy keys | | |
| 369 | 375 | | `team` | Teams and their members and repositories | | |
| 370 | − | | `workspace` | Workspaces, members, integrations, projects, rulesets and token rules | | |
| 376 | + | | `workspace` | Workspaces, members, labels, milestones, integrations, projects, rulesets and token rules | | |
| 371 | 377 | | `ai` | The workspace's AI providers, and what Ask answers with | | |
| 372 | 378 | | `billing` | Usage, budget and invoices | | |
| 373 | 379 | | `notifications` | Your inbox | | |
| ⋯ | |||
| 407 | 413 | In the ChatGPT desktop app's Plugins directory, select the **g1t** marketplace, | |
| 408 | 414 | install **g1t**, and authorize its MCP connection. Restart the app if the source | |
| 409 | 415 | has not appeared. The plugin bundles the MCP server and a skill for working on | |
| 410 | − | g1t issues and recording sessions. It does not install Claude Code's hooks. | |
| 416 | + | g1t work items and recording sessions. It does not install Claude Code's hooks. | |
| 411 | 417 | If you already added the standalone `g1t` MCP server, disable that duplicate | |
| 412 | 418 | connection when using the plugin. | |
| 413 | 419 | ||
| 41 | 41 | | | The g1t CLI | g1t's MCP tools | | |
| 42 | 42 | | --- | --- | --- | | |
| 43 | 43 | | Signed in by | `g1t auth login` | `/mcp`, **plugin:g1t:g1t** | | |
| 44 | − | | What it may do | Everything you can: the sign-in carries every scope, bounded by your roles | The [Agent preset](/guides/authentication/#presets), unless you change it: reading across g1t, creating repositories, and writing code, issues, pull requests and notifications | | |
| 44 | + | | What it may do | Everything you can: the sign-in carries every scope, bounded by your roles | The [Agent preset](/guides/authentication/#presets), unless you change it: reading across g1t, creating repositories, and writing code, work items, pull requests and notifications | | |
| 45 | 45 | | Creates a repository | Yes | Yes, with `repo:create` | | |
| 46 | 46 | ||
| 47 | 47 | The plugin's skills and hooks use the CLI, so Claude reaches for `g1t` | |
| ⋯ | |||
| 88 | 88 | whose remote is on g1t, and this folder had none when the session | |
| 89 | 89 | started. Start Claude Code again with `claude --continue`: the | |
| 90 | 90 | conversation carries on, and from then on the session is recorded, shows | |
| 91 | − | in **Live now** on the project's **Work** page, and is tied to the | |
| 91 | + | in **Live now** on the project's **Sessions** page, and is tied to the | |
| 92 | 92 | commits and pull requests it makes. To record it all, create the | |
| 93 | 93 | repository first yourself, `g1t repo create acme/my-app --clone`, and | |
| 94 | 94 | start Claude Code in the clone. | |
| ⋯ | |||
| 100 | 100 | through a pull request. Ask: | |
| 101 | 101 | ||
| 102 | 102 | ```text | |
| 103 | − | Add a contact page to my-app. Open an issue for it, work on a branch, | |
| 103 | + | Add a contact page to my-app. Open a work item for it, work on a branch, | |
| 104 | 104 | open a pull request on g1t, wait for its checks, and merge it when they | |
| 105 | 105 | pass. | |
| 106 | 106 | ``` | |
| 107 | 107 | ||
| 108 | − | The agent works as the plugin's `/g1t:work-on-issue` skill says: | |
| 108 | + | The agent works as the plugin's `/g1t:work-on-item` skill says: | |
| 109 | 109 | ||
| 110 | 110 | | The agent | With the CLI | With MCP | | |
| 111 | 111 | | --- | --- | --- | | |
| 112 | − | | Opens an issue and claims it for this session | `g1t work claim --title "Add a contact page"` | `issue` `claim` with a `title` | | |
| 113 | − | | Makes a branch named for the issue, such as `1-contact-page`, and commits with the trailer `G1t-Session: $G1T_SESSION` | `git commit --trailer "G1t-Session: $G1T_SESSION"` | | | |
| 114 | − | | Opens a draft pull request early | `g1t pr create --issue 1 --draft --fill` | `pull_request` `create` | | |
| 112 | + | | Opens a work item and claims it for this session | `g1t work claim --title "Add a contact page"` | `work_item` `claim` with a `title` | | |
| 113 | + | | Makes a branch named for the work item, such as `1-contact-page`, and commits with the trailer `G1t-Session: $G1T_SESSION` | `git commit --trailer "G1t-Session: $G1T_SESSION"` | | | |
| 114 | + | | Opens a draft pull request early | `g1t pr create --item 1 --draft --fill` | `pull_request` `create` with `item` | | |
| 115 | 115 | | Watches the checks | `g1t pr checks --watch --fail-fast` | `pull_request` `get` | | |
| 116 | 116 | | Marks it ready, with what changed and why | `g1t pr ready --summary "…"` | `pull_request` `ready` | | |
| 117 | 117 | | Merges it | `g1t pr merge` | `pull_request` `merge` | | |
| 118 | 118 | ||
| 119 | 119 | `g1t work claim` prints `Opened #1 Add a contact page.` and | |
| 120 | 120 | `Claimed #1.`; `g1t pr merge` prints `Merged acme/my-app#2`. Merging | |
| 121 | − | into the default branch closes the issue. The trailer ties each commit, | |
| 121 | + | into the default branch closes the work item. The trailer ties each commit, | |
| 122 | 122 | and the pull request it lands in, to the session; the pull request's | |
| 123 | 123 | **Session** tab shows how it was made. See | |
| 124 | 124 | [Sessions, claims and dependencies](/guides/sessions/). | |
| ⋯ | |||
| 202 | 202 | | --- | --- | --- | --- | | |
| 203 | 203 | | Create a repository | Yes | `g1t repo create`, or `repository` `create` | `repo:create`, which the Agent preset gives | | |
| 204 | 204 | | Push code | Yes | git, with the CLI's credentials (`g1t auth setup-git`) or an [access token](/guides/authentication/#access-tokens) | `code:write`; a workflow file also needs `workflow_files:write` | | |
| 205 | − | | Open and claim an issue | Yes | `g1t work claim`, or `issue` `claim` | `issues:write` | | |
| 205 | + | | Open and claim a work item | Yes | `g1t work claim`, or `work_item` `claim` | `work:write` | | |
| 206 | 206 | | Open a pull request and mark it ready | Yes | `g1t pr create` and `g1t pr ready`, or `pull_request` `create` and `ready` | `pull_requests:write` | | |
| 207 | 207 | | Watch checks and the preview | Yes | `g1t pr checks --watch`, or `pull_request` `get` | `pull_requests:read` | | |
| 208 | 208 | | Merge | Yes, within the repository's rules | `g1t pr merge`, or `pull_request` `merge` | `pull_requests:write`, and the Write role | | |
| ⋯ | |||
| 223 | 223 | that has no repository yet, though, and it proposes a session for a new | |
| 224 | 224 | one. When you choose **Start session** or **Copy Claude Code command** on | |
| 225 | 225 | that card, your click creates the repository, turns on its deployments | |
| 226 | − | (with the g1t plan), opens the issue and starts the session, which pushes | |
| 226 | + | (with the g1t plan), opens the work item and starts the session, which pushes | |
| 227 | 227 | the first version and watches it go live. See | |
| 228 | 228 | [Building something new](/guides/ask/#building-something-new). | |
| 347 | 347 | | Session | Length | Who | | |
| 348 | 348 | | --- | --: | --- | | |
| 349 | 349 | | Welcome and tour | 45 min | Ana | | |
| 350 | − | | Your first issue | 60 min | Margo | | |
| 350 | + | | Your first work item | 60 min | Margo | | |
| 351 | 351 | ``` | |
| 352 | 352 | ||
| 353 | 353 | Chat never shows HTML: `<b>` reads as typed. An image written in Markdown |
| 1 | 1 | --- | |
| 2 | 2 | title: Claude Code plugin | |
| 3 | − | description: Install g1t's plugin for Claude Code, which records your sessions on g1t, gives Claude the issue's work context, and adds g1t's MCP server, skills and commands. What each hook records and never records, and how to opt out. | |
| 3 | + | description: Install g1t's plugin for Claude Code, which records your sessions on g1t, gives Claude the work item's work context, and adds g1t's MCP server, skills and commands. What each hook records and never records, and how to opt out. | |
| 4 | 4 | --- | |
| 5 | 5 | ||
| 6 | 6 | g1t's plugin for Claude Code connects the sessions you run on your own | |
| ⋯ | |||
| 8 | 8 | ||
| 9 | 9 | - each Claude Code session is recorded on g1t as a | |
| 10 | 10 | [session](/guides/why-blame/#sessions), titled with what you asked for | |
| 11 | − | and attached to its issue and pull request, so the people and agents | |
| 12 | − | also working there can see it, issue or not; | |
| 13 | − | - Claude starts each session knowing the issue it is on: its definition of | |
| 14 | − | done, who has claimed it, its pull requests and what blocks it; | |
| 11 | + | and attached to its work item and pull request, so the people and agents | |
| 12 | + | also working there can see it, work item or not; | |
| 13 | + | - Claude starts each session knowing the work item it is on: its definition | |
| 14 | + | of done, the repositories it is meant to land in, who has claimed it, its | |
| 15 | + | pull requests and what blocks it; | |
| 15 | 16 | - Claude has g1t's [MCP tools](/reference/mcp/), three skills for working | |
| 16 | − | on issues, and the commands `/g1t:claim`, `/g1t:status` and | |
| 17 | + | on work items, and the commands `/g1t:claim`, `/g1t:status` and | |
| 17 | 18 | `/g1t:handoff`. | |
| 18 | 19 | ||
| 19 | 20 | Your session runs where it always does. g1t keeps the record and the | |
| ⋯ | |||
| 21 | 22 | ||
| 22 | 23 | ## Install | |
| 23 | 24 | ||
| 24 | − | You need Claude Code, the [g1t CLI](/guides/cli/) 0.3.2 or later, which | |
| 25 | + | You need Claude Code, the [g1t CLI](/guides/cli/) 0.4.0 or later, which | |
| 25 | 26 | the plugin's hooks use, and Node 18 or later on your `PATH`, which runs | |
| 26 | 27 | them. Claude Code's native installer does not bring Node with it: run | |
| 27 | 28 | `node --version` to check, and install it from | |
| ⋯ | |||
| 81 | 82 | ||
| 82 | 83 | `flagon-io/g1t-plugins` is published from g1t's repository, where the | |
| 83 | 84 | plugin is developed and tested (`plugins/claude-code/`). Every change there | |
| 84 | − | is published automatically, so the two never differ; issues and changes | |
| 85 | + | is published automatically, so the two never differ; work items and changes | |
| 85 | 86 | go to [flagon-io/g1t](https://g1t.sh/flagon-io/g1t). | |
| 86 | 87 | ||
| 87 | 88 | ## What it records | |
| ⋯ | |||
| 100 | 101 | | You send a prompt | `g1t session log --kind prompt TEXT` | Your prompt's first 2,000 characters. | | |
| 101 | 102 | | You send a prompt that says what it is for, while the session has no title | `g1t session heartbeat --json`, then, if the session has no title, `g1t session attach --title INTENT` | Its title: what the prompt is for, as its first line or sentence without pasted text, image placeholders (`[Image #1]`), code blocks or markdown, up to 80 characters, cut on a word with `…`. A slash command, or a prompt that is only pasted text or images, gives no title, and the next prompt titles the session. A title the session already has (one Claude, you or an earlier prompt set) is never replaced. Not sent with prompts kept back. | | |
| 102 | 103 | | Claude uses a tool | `g1t session log --kind tool_call TEXT` | The tool's name and one line on what it was called with: the command, file, pattern or address, up to 200 characters, with anything that looks like a token or password replaced by `…`. | | |
| 103 | − | | Claude uses a skill, or you run one (`/g1t:work-on-issue 42`) | `g1t session log --kind skill NAME` | The skill's name, nothing more, once in a turn. A plugin's skill or command you type as `/plugin:name` is recorded even with prompts kept back. | | |
| 104 | − | | Claude writes a file, makes a branch or a commit, or claims an issue | `g1t session touch --file PATH` (or `--branch`, `--commit`, `--issue`) | What it touched: the path from the repository's root, the branch, the commit, the issue. A file is one Claude edited or wrote, or one a shell command changed while it ran (the uncommitted files before and after it), never what was uncommitted already, so sessions sharing a working copy do not claim each other's work. g1t ties the session to the pull requests and issues these lead to, and tells two sessions that touch the same file. | | |
| 104 | + | | Claude uses a skill, or you run one (`/g1t:work-on-item 42`) | `g1t session log --kind skill NAME` | The skill's name, nothing more, once in a turn. A plugin's skill or command you type as `/plugin:name` is recorded even with prompts kept back. | | |
| 105 | + | | Claude writes a file, makes a branch or a commit, or claims a work item | `g1t session touch --file PATH` (or `--branch`, `--commit`, `--item`) | What it touched: the path from the repository's root, the branch, the commit, the work item. A file is one Claude edited or wrote, or one a shell command changed while it ran (the uncommitted files before and after it), never what was uncommitted already, so sessions sharing a working copy do not claim each other's work. g1t ties the session to the pull requests and work items these lead to, and tells two sessions that touch the same file. | | |
| 105 | 106 | | A `git push` reaches the remote | `g1t api update_session -f id=ID -f head_commit=SHA` and `g1t session touch --commit SHA --branch BRANCH` | The commit you pushed and its branch, so the session's entries line up with the code and it is tied to the branch's pull request. | | |
| 106 | 107 | | Claude starts a subagent | `g1t session start --parent SESSION --agent-type TYPE --task TASK --prompt PROMPT` | A session of its own for the subagent, under this one, with its kind and the task it was given (its prompt's first 4,000 characters). See [Subagents](#subagents). | | |
| 107 | 108 | | A subagent finishes | `g1t session end --result MESSAGE` | Its final message, up to 8,000 characters: what it reported to Claude. | | |
| ⋯ | |||
| 137 | 138 | ||
| 138 | 139 | ## The context Claude starts with | |
| 139 | 140 | ||
| 140 | − | When a session starts, the plugin looks for the issue it is working on: | |
| 141 | − | the one the session claimed earlier, or a number in the branch's name | |
| 142 | − | (`42-fix-login`, `issue-42`, `fix/42`). If it finds one, it runs | |
| 143 | − | `g1t work context N` and gives Claude the answer: the issue and its | |
| 144 | − | definition of done, its claims and sessions, its pull requests with their | |
| 141 | + | When a session starts, the plugin looks for the work item it is working | |
| 142 | + | on: the one the session claimed earlier, or a number in the branch's name | |
| 143 | + | (`42-fix-login`, `item-42`, `fix/42`). The number is the work item's in | |
| 144 | + | the repository's workspace; an old issue number in a branch name still | |
| 145 | + | finds the work item it became. If it finds one, it runs `g1t work view N` | |
| 146 | + | and gives Claude the answer: the work item and its definition of done, the | |
| 147 | + | repositories it is linked to and which have landed, its claims and sessions, its pull requests with their | |
| 145 | 148 | checks and overlaps, what blocks it and what it blocks, the decisions | |
| 146 | 149 | recorded on it and the last integration failure. If the answer takes longer | |
| 147 | 150 | than a second, Claude is told to load it itself. | |
| 148 | 151 | ||
| 149 | − | With no issue in sight, Claude is told that the session is already | |
| 152 | + | With no work item in sight, Claude is told that the session is already | |
| 150 | 153 | recorded on g1t and shows to the team with what it is for, so it can just | |
| 151 | − | work; see [Work with no issue yet](#work-with-no-issue-yet). | |
| 154 | + | work; see [Work with no work item yet](#work-with-no-work-item-yet). | |
| 152 | 155 | ||
| 153 | 156 | Claude is also told to put the trailer `G1t-Session: $G1T_SESSION` on the | |
| 154 | 157 | commits it makes, so g1t ties them, and the pull request they land in, to | |
| 155 | 158 | the session, and that a commit pushed straight to the default branch which | |
| 156 | − | finishes an issue says `Closes #N` in its message: a bare `(#N)` only links | |
| 157 | − | the issue (see [Closing issues](/guides/pull-requests/#closing-issues)). | |
| 159 | + | finishes a work item says `Closes #N` in its message (`Part of #N` when it | |
| 160 | + | does only part): a bare `(#N)` only links the work item (see | |
| 161 | + | [Closing work items](/guides/pull-requests/#closing-work-items)). | |
| 158 | 162 | ||
| 159 | 163 | A session started from a hand-off (**Start a session** without an | |
| 160 | 164 | Anthropic [AI provider](/guides/ai/), or `g1t work dispatch N --handoff`) runs as | |
| 161 | − | `G1T_ISSUE=N claude '…'`: the plugin attaches it to issue N as it starts. | |
| 165 | + | `G1T_ITEM=N claude '…'`: the plugin attaches it to work item N as it starts. | |
| 162 | 166 | ||
| 163 | − | ## Work with no issue yet | |
| 167 | + | ## Work with no work item yet | |
| 164 | 168 | ||
| 165 | − | Most sessions start from a question or a request, not an issue, and most | |
| 166 | − | never need one. The session is the record of that work: | |
| 169 | + | Most sessions start from a question or a request, not a work item, and | |
| 170 | + | most never need one. The session is the record of that work: | |
| 167 | 171 | ||
| 168 | 172 | 1. **It is titled with what it is for.** At the session's first prompt | |
| 169 | 173 | that says what it is for, the plugin gives the session a title from | |
| ⋯ | |||
| 181 | 185 | out to be something else: the plugin tells it at the start that it | |
| 182 | 186 | can retitle the session, and reminds it at the second prompt and every | |
| 183 | 187 | fifth after (not while the CLI is signed out or too old). | |
| 184 | − | 2. **It shows to the team.** The project's overview and its **Work** page | |
| 188 | + | 2. **It shows to the team.** The project's overview and its **Sessions** page | |
| 185 | 189 | list it in **Live now** under its pull request, else its branch, else | |
| 186 | 190 | under **No branch yet**, with who it is for, Claude Code, its state, | |
| 187 | 191 | when it was last heard from and its branch. | |
| 188 | − | 3. **It gets an issue when it becomes a change** others should know about: | |
| 189 | − | a branch to push, a pull request. Claude is told to look for an issue | |
| 190 | − | first (`g1t work list`, `g1t issue list`) and claim it with | |
| 191 | − | `g1t work claim N`, and if there is none, to open one and claim it in | |
| 192 | − | one step: | |
| 192 | + | 3. **It gets a work item when it becomes a change** others should know | |
| 193 | + | about: a branch to push, a pull request. Claude is told to look for a | |
| 194 | + | work item first (`g1t work list`) and claim it with `g1t work claim N`, | |
| 195 | + | and if there is none, to open one and claim it in one step: | |
| 193 | 196 | ||
| 194 | 197 | ```sh | |
| 195 | 198 | g1t work claim --title "Preview builds time out on large repositories" | |
| 196 | 199 | ``` | |
| 197 | 200 | ||
| 198 | − | The issue is opened, claimed for this session, and the session is | |
| 199 | − | attached to it, so **Live now** lists it under the issue from then on. | |
| 200 | − | Claude is told never to open issues for questions, exploration or | |
| 201 | + | The work item is opened in the repository's workspace, with the | |
| 202 | + | repository as its origin, claimed for this session, and the session is | |
| 203 | + | attached to it, so **Live now** lists it under the work item from then | |
| 204 | + | on. Claude is told never to open work items for questions, exploration or | |
| 201 | 205 | trivial fixes. `/g1t:claim` with a title instead of a number does the | |
| 202 | 206 | same. | |
| 203 | 207 | ||
| 204 | 208 | ## Subagents | |
| 205 | 209 | ||
| 206 | 210 | Each subagent Claude Code starts is recorded as a session of its own, | |
| 207 | − | under the session that started it, so if Claude hands parts of an issue to | |
| 211 | + | under the session that started it, so if Claude hands parts of a work item to | |
| 208 | 212 | twelve subagents, g1t shows twelve sessions and they see each other. | |
| 209 | 213 | ||
| 210 | 214 | - **When it starts** (`SubagentStart`), the plugin starts its session with | |
| ⋯ | |||
| 213 | 217 | prompt of the Agent call, kept from the moment Claude made it | |
| 214 | 218 | (`PreToolUse`) and matched to the subagent by the call's id or its | |
| 215 | 219 | prompt, so subagents started together each get their own. The subagent is told it has a session of its own, to | |
| 216 | − | look at its siblings with `g1t session list --issue N --subagents` | |
| 220 | + | look at its siblings with `g1t session list --item N --subagents` | |
| 217 | 221 | before changing anything, and to claim only what it takes. | |
| 218 | 222 | - **While it works**, what it does is recorded in its own session, not its | |
| 219 | 223 | parent's: its tool calls, the skills it uses and the files it touches. | |
| ⋯ | |||
| 249 | 253 | ||
| 250 | 254 | | Skill | What it does | | |
| 251 | 255 | | --- | --- | | |
| 252 | − | | `/g1t:work-on-issue N` | Loads the issue's context, claims it, makes a branch named for it, opens a draft pull request early with `g1t pr create --issue N --draft`, does the work, watches the checks and merges, or adds the pull request to the [merge queue](/guides/merge-queue/). | | |
| 256 | + | | `/g1t:work-on-item N` | Loads the work item's context, claims it, makes a branch named for it, opens a draft pull request early with `g1t pr create --item N --draft`, does the work, watches the checks and merges, or adds the pull request to the [merge queue](/guides/merge-queue/). | | |
| 253 | 257 | | `/g1t:fix-integration N` | For a pull request the merge queue failed together with others: reads the `integration.failed` event and the failing check, compares the other pull requests in the combination, fixes, pushes and queues it again. | | |
| 254 | − | | `/g1t:coordinate N` | Follows the issue's events in the background with `g1t work events --follow --issue N`, and acts on another claim, an overlapping pull request, a change to what blocks it or an integration result as it happens. | | |
| 258 | + | | `/g1t:coordinate N` | Follows the work item's events in the background with `g1t work events --follow --item N`, and acts on another claim, an overlapping pull request, a change to what blocks it or an integration result as it happens. | | |
| 255 | 259 | ||
| 256 | 260 | ## Commands | |
| 257 | 261 | ||
| 258 | 262 | | Command | What it does | | |
| 259 | 263 | | --- | --- | | |
| 260 | − | | `/g1t:claim N [note]` | Loads issue N's context and claims it for this session, telling you who else holds a claim. With a title instead of a number (or nothing), looks for an issue that covers the work in hand, and opens and claims one with `g1t work claim --title` if there is none. | | |
| 261 | − | | `/g1t:status` | This session (its title, issue, branch or pull request), and the repository's active claims and sessions. | | |
| 262 | − | | `/g1t:handoff N [@login]` | Pushes what is unpushed, writes a hand-off note and hands the issue off, to anyone or to one person. | | |
| 264 | + | | `/g1t:claim N [note]` | Loads work item N's context and claims it for this session, telling you who else holds a claim. With a title instead of a number (or nothing), looks for a work item that covers the work in hand, and opens and claims one with `g1t work claim --title` if there is none. | | |
| 265 | + | | `/g1t:status` | This session (its title, work item, branch or pull request), and the repository's active claims and sessions. | | |
| 266 | + | | `/g1t:handoff N [@login]` | Pushes what is unpushed, writes a hand-off note and hands the work item off, to anyone or to one person. | | |
| 263 | 267 | ||
| 264 | − | A claim says you are working on an issue. It is never a lock: a second | |
| 268 | + | A claim says you are working on a work item. It is never a lock: a second | |
| 265 | 269 | claim is allowed, and whoever makes it is told about the first. | |
| 266 | 270 | ||
| 267 | 271 | ## When the CLI is missing, signed out or out of date | |
| 268 | 272 | ||
| 269 | − | If `g1t` is not installed, not signed in, or older than 0.3.2 (the oldest | |
| 273 | + | If `g1t` is not installed, not signed in, or older than 0.4.0 (the oldest | |
| 270 | 274 | that takes every command the hooks run), the hooks record nothing and | |
| 271 | 275 | Claude Code says so once. The plugin never installs anything itself. | |
| 272 | 276 | Install the CLI or run `g1t auth login`, and the next session is recorded. | |
| ⋯ | |||
| 309 | 313 | { "env": { "G1T_RECORD_PROMPTS": "0" } } | |
| 310 | 314 | ``` | |
| 311 | 315 | ||
| 312 | − | A recorded session can be read on its own page, linked from the issue, the | |
| 313 | − | pull request's **Session** tab and the repository's **Work** page: who ran | |
| 316 | + | A recorded session can be read on its own page, linked from the work item, the | |
| 317 | + | pull request's **Session** tab and the repository's **Sessions** page: who ran | |
| 314 | 318 | it, its subagents as a tree, the skills used, what it touched, and the | |
| 315 | − | issues and pull requests it worked on. | |
| 319 | + | work items and pull requests it worked on. | |
| 316 | 320 | ||
| 317 | 321 | ## Other coding agents | |
| 318 | 322 | ||
| ⋯ | |||
| 336 | 340 | few minutes and `g1t session end` when you stop. Only create subagents | |
| 337 | 341 | when the user's task permits delegation; give each its own session with | |
| 338 | 342 | `--parent PARENT_ID --no-remember` and its own G1T_SESSION. | |
| 339 | − | - With no issue, just work: the session shows to the team. When the work | |
| 340 | − | becomes a change others should know about (a branch to push, a pull | |
| 341 | − | request), look for its issue (`g1t work list`, `g1t issue list`) and | |
| 342 | − | claim it; if there is none, open and claim one with | |
| 343 | − | `g1t work claim --title "TITLE"`. Never open issues for questions, | |
| 344 | − | exploration or trivial fixes. | |
| 345 | − | - Before working on an issue, load it with `g1t work context N`: its | |
| 346 | − | definition of done, who has claimed it, its pull requests, checks and | |
| 343 | + | - With no work item, just work: the session shows to the team. When the | |
| 344 | + | work becomes a change others should know about (a branch to push, a pull | |
| 345 | + | request), look for its work item (`g1t work list`) and claim it; if | |
| 346 | + | there is none, open and claim one with `g1t work claim --title "TITLE"`. | |
| 347 | + | Never open work items for questions, exploration or trivial fixes. | |
| 348 | + | - Work items belong to the workspace and can span several repositories. | |
| 349 | + | Before working on one, load it with `g1t work view N`: its definition of | |
| 350 | + | done, the repositories it targets and which have landed, who has claimed it, its pull requests, checks and | |
| 347 | 351 | overlaps, and what blocks it. Then claim it with | |
| 348 | 352 | `g1t work claim N --note "Scope: ...; Interfaces: ...; Depends on: ...; Checks: ..."`. | |
| 349 | 353 | Proceed on complementary scopes. Before editing overlapping files or | |
| ⋯ | |||
| 367 | 371 | `update`, and `end`. Keep the returned ID and pass it explicitly. To read | |
| 368 | 372 | pending updates without the transcript, call `get` with `after: 4294967295`. | |
| 369 | 373 | `record` accepts `entries` for the decision and `acknowledge: [IDs]`. | |
| 370 | − | Use `issue` action `work` to refresh issue context and `claim` with your | |
| 374 | + | Use `work_item` action `work` to refresh work item context and `claim` with your | |
| 371 | 375 | `session_id` and scope note. The same session ownership rules apply. | |
| 372 | − | - Work on a branch whose name starts with the issue number | |
| 376 | + | - Work on a branch whose name starts with the work item's number | |
| 373 | 377 | (`42-short-description`), and open a draft pull request early: | |
| 374 | − | `g1t pr create --issue N --draft --fill`. | |
| 378 | + | `g1t pr create --item N --draft --fill`. When it finishes this | |
| 379 | + | repository's part, its description says `Closes #N`; when it does only | |
| 380 | + | part, `Part of #N`. | |
| 375 | 381 | - Log decisions worth keeping with `g1t session log --kind note "TEXT"`. | |
| 376 | 382 | Never log secrets or command output. | |
| 377 | 383 | - Run the repository's tests before each push, and watch the checks with | |
| 378 | 384 | `g1t pr checks --watch --fail-fast` (and `g1t run logs --failed` for why | |
| 379 | 385 | one failed). When the merge queue reports an integration failure, read | |
| 380 | − | it with `g1t work events --type integration.failed --issue N`, diff the | |
| 386 | + | it with `g1t work events --type integration.failed --item N`, diff the | |
| 381 | 387 | other pull requests in the combination (`g1t pr diff OTHER`), fix, push | |
| 382 | 388 | and merge again. | |
| 383 | − | - If you stop before the issue is done, hand it off with the exact commit, | |
| 389 | + | - If you stop before the work item is done, hand it off with the exact commit, | |
| 384 | 390 | completed scope, remaining work, checks actually run and their results, | |
| 385 | 391 | blockers, and next action: `g1t work handoff N --note "..."`. | |
| 386 | − | A successor reads the issue context and predecessor's session before | |
| 392 | + | A successor reads the work item context and predecessor's session before | |
| 387 | 393 | editing, verifies the recorded commit and evidence, and logs its plan. | |
| 388 | 394 | Recorded claims or decisions are not proof that tests passed. | |
| 389 | 395 | ``` | |
| 1 | 1 | --- | |
| 2 | 2 | title: The g1t CLI | |
| 3 | − | description: Install the g1t command line, sign in, and work with repositories, issues, pull requests, runs, workflows, deployments, secrets and logs from a terminal, a script or an agent. | |
| 3 | + | description: Install the g1t command line, sign in, and work with repositories, work items, pull requests, runs, workflows, deployments, secrets and logs from a terminal, a script or an agent. | |
| 4 | 4 | --- | |
| 5 | 5 | ||
| 6 | 6 | `g1t` is the command line for g1t. It does the work you would otherwise do on | |
| ⋯ | |||
| 12 | 12 | exit codes say what happened. | |
| 13 | 13 | ||
| 14 | 14 | ```sh | |
| 15 | − | g1t issue list --label bug | |
| 15 | + | g1t work list --label bug | |
| 16 | 16 | g1t pr create --fill | |
| 17 | 17 | g1t pr checks --watch --fail-fast | |
| 18 | 18 | g1t run logs --failed | |
| ⋯ | |||
| 208 | 208 | `G1T_REPO`: | |
| 209 | 209 | ||
| 210 | 210 | ```sh | |
| 211 | − | g1t issue list -R acme/web | |
| 211 | + | g1t pr list -R acme/web | |
| 212 | 212 | g1t pr view 14 -R git.example.com/acme/web | |
| 213 | 213 | ``` | |
| 214 | 214 | ||
| ⋯ | |||
| 234 | 234 | your own workspace, or `--workspace`; see | |
| 235 | 235 | [forking a repository](/guides/forking-repositories/). | |
| 236 | 236 | ||
| 237 | − | ### Issues | |
| 237 | + | ### Work items | |
| 238 | 238 | ||
| 239 | 239 | ```sh | |
| 240 | − | g1t issue list # open issues, newest first | |
| 241 | − | g1t issue list --label bug --assignee @me | |
| 242 | − | g1t issue view 12 --comments | |
| 243 | − | g1t issue create -t "Greeting should name the caller" -b "Take a name from the first argument." | |
| 244 | − | g1t issue comment 12 -b "Fixed in #14." | |
| 245 | − | g1t issue edit 12 --add-label p1 --add-assignee @me | |
| 246 | − | g1t issue close 12 --reason not_planned | |
| 240 | + | g1t work list # open work items, newest first | |
| 241 | + | g1t work list --label bug --assignee @me | |
| 242 | + | g1t work list --repo acme/web # those linked to one repository | |
| 243 | + | g1t work view 12 --comments | |
| 244 | + | g1t work new --title "Greeting should name the caller" --body "Take a name from the first argument." | |
| 245 | + | g1t work comment 12 -b "Fixed in #14." | |
| 246 | + | g1t work edit 12 --add-label p1 --add-assignee @me | |
| 247 | + | g1t work link 12 --role target --repo acme/api | |
| 248 | + | g1t work unlink 12 --repo acme/api | |
| 249 | + | g1t work close 12 --reason not_planned | |
| 250 | + | g1t work reopen 12 | |
| 247 | 251 | ``` | |
| 248 | 252 | ||
| 249 | − | `@me` is you. At a terminal, `g1t issue create` without `--title` asks for | |
| 250 | − | one and opens your editor for the body. | |
| 253 | + | [Work items](/guides/work-items/) belong to the workspace, and `g1t work` | |
| 254 | + | works on the current repository's workspace, or the one in `--workspace`. | |
| 255 | + | `g1t work new` makes the current repository the new work item's origin. | |
| 256 | + | `g1t work view` shows the work item with its whole work context (see | |
| 257 | + | [Claims and context](#claims-and-context)). `@me` is you. At a terminal, | |
| 258 | + | `g1t work new` without `--title` asks for one and opens your editor for | |
| 259 | + | the body. | |
| 251 | 260 | ||
| 252 | 261 | ### Images in descriptions and comments | |
| 253 | 262 | ||
| ⋯ | |||
| 261 | 270 | g1t pr ready --summary "Names the caller." --attach preview.png | |
| 262 | 271 | ``` | |
| 263 | 272 | ||
| 264 | − | `--attach FILE` (repeat it for more) on `g1t issue create`, `g1t issue comment`, | |
| 273 | + | `--attach FILE` (repeat it for more) on `g1t work new`, `g1t work comment`, | |
| 265 | 274 | `g1t pr create`, `g1t pr comment` and `g1t pr ready` uploads each file and adds | |
| 266 | 275 | its Markdown after the text. An attachment is a PNG, JPEG, GIF or WebP image of | |
| 267 | 276 | at most 10 MB, judged by its bytes. It is served from g1t's usercontent address, | |
| 268 | 277 | never from g1t.sh, and its address is its permission: anyone given it can see | |
| 269 | 278 | the image, even from a private repository. Never commit an image to the | |
| 270 | 279 | repository just to link it. Through the API it is | |
| 271 | − | [`upload_attachment`](/reference/api/issues/upload-attachment/). | |
| 280 | + | [`upload_attachment`](/reference/api/work-items/upload-attachment/). | |
| 272 | 281 | ||
| 273 | 282 | ### Pull requests | |
| 274 | 283 | ||
| ⋯ | |||
| 277 | 286 | ```sh | |
| 278 | 287 | git switch -c greet-by-name | |
| 279 | 288 | # ...commit... | |
| 280 | − | g1t pr create --fill --issue 12 | |
| 289 | + | g1t pr create --fill --item 12 | |
| 281 | 290 | ``` | |
| 282 | 291 | ||
| 283 | 292 | `g1t pr create` pushes the branch, then opens the pull request into the | |
| 284 | 293 | default branch (`--base` for another). `--fill` takes the title and body from | |
| 285 | − | the branch's commits; `--issue` says which issue it is for; `--draft` opens | |
| 286 | − | it as a draft. | |
| 294 | + | the branch's commits; `--item` says which work item it is for, by its | |
| 295 | + | number in the workspace; `--draft` opens it as a draft. | |
| 287 | 296 | ||
| 288 | − | To start a pull request for an issue without a branch of your own, as | |
| 289 | − | coding agents usually do, run it with `--issue` from the default branch. g1t opens a draft | |
| 297 | + | To start a pull request for a work item without a branch of your own, as | |
| 298 | + | coding agents usually do, run it with `--item` from the default branch. g1t opens a draft | |
| 290 | 299 | with a [working copy](/concepts/forks/#working-copies-for-pull-requests) of its own and prints the | |
| 291 | 300 | copy's git remote. Push your commits there, then mark it ready with a | |
| 292 | 301 | summary of what changed and why: | |
| 293 | 302 | ||
| 294 | 303 | ```sh | |
| 295 | − | g1t pr create --issue 12 | |
| 304 | + | g1t pr create --item 12 | |
| 296 | 305 | git push https://g1t.sh/pulls/pr_….git HEAD:main | |
| 297 | 306 | g1t pr ready --summary "Reads a name from the first argument." | |
| 298 | 307 | ``` | |
| ⋯ | |||
| 425 | 434 | after it use it: | |
| 426 | 435 | ||
| 427 | 436 | ```sh | |
| 428 | − | g1t session start --harness claude-code --issue 12 | |
| 437 | + | g1t session start --harness claude-code --item 12 | |
| 429 | 438 | g1t session log "Split the parser before touching the lexer." | |
| 430 | 439 | g1t session attach --pull 14 --head-commit "$(git rev-parse HEAD)" | |
| 431 | 440 | g1t session heartbeat | |
| ⋯ | |||
| 434 | 443 | ||
| 435 | 444 | | Command | What it does | | |
| 436 | 445 | | --- | --- | | |
| 437 | − | | `g1t session start` | Starts a session and prints its id. `--harness` (`claude_code`, `codex`, `cursor`, `copilot` or `other`; `claude-code` works too), `--harness-session-id`, `--issue`, `--pull`, `--branch` (the current one by default) and `--title`. Starting again with the same `--harness-session-id` returns the same session. For a subagent, `--parent` (the session that started it), `--agent-type`, `--task`, `--prompt` and `--model`; a subagent's session is not kept as the working copy's (nor is one with `--no-remember`). | | |
| 446 | + | | `g1t session start` | Starts a session and prints its id. `--harness` (`claude_code`, `codex`, `cursor`, `copilot` or `other`; `claude-code` works too), `--harness-session-id`, `--item`, `--pull`, `--branch` (the current one by default) and `--title`. Starting again with the same `--harness-session-id` returns the same session. For a subagent, `--parent` (the session that started it), `--agent-type`, `--task`, `--prompt` and `--model`; a subagent's session is not kept as the working copy's (nor is one with `--no-remember`). | | |
| 438 | 447 | | `g1t session heartbeat` | Says the session is still working, and renews its claims. A session with no heartbeat for 15 minutes reads as idle, and after 30 minutes as ended; a heartbeat brings it back. | | |
| 439 | 448 | | `g1t session log TEXT` | Records a note. `--kind` takes `note`, `prompt`, `message`, `tool_call` (or `tool-call`) or `skill` (a skill's name), `--tool` names the tool, and `--key` makes recording the same entry twice do nothing. `-` reads the text from stdin; put `--` before text that starts with a dash. | | |
| 440 | − | | `g1t session attach` | Points the session at an `--issue`, a `--pull`, a `--branch` or its latest `--head-commit`, or gives it a `--title`: what it is for, which replaces the title it had. | | |
| 441 | − | | `g1t session touch` | Says what the session touched: `--file PATH`, `--commit SHA`, `--branch NAME`, `--pull N` (one it opened), `--issue N`, each repeatable. Ties the session to the pull requests and issues they lead to; a file another active session touched too is an `overlap.detected` for both. | | |
| 449 | + | | `g1t session attach` | Points the session at an `--item`, a `--pull`, a `--branch` or its latest `--head-commit`, or gives it a `--title`: what it is for, which replaces the title it had. | | |
| 450 | + | | `g1t session touch` | Says what the session touched: `--file PATH`, `--commit SHA`, `--branch NAME`, `--pull N` (one it opened), `--item N`, each repeatable. Ties the session to the pull requests and work items they lead to; a file another active session touched too is an `overlap.detected` for both. | | |
| 442 | 451 | | `g1t session updates [ID]` | What other sessions did that concerns this one (claims, overlaps, dependency changes, decisions, merge queue results), oldest first, up to 100. Reading never clears them. It first says which files the working copy changed, so overlapping edits are noticed (`G1T_TOUCH=0` turns that off). | | |
| 443 | 452 | | `g1t session acknowledge ID... --note TEXT` | Records your decision about those updates (what changes in your plan, or why nothing does) and clears exactly the IDs given, for this session only; `--session` names another of yours. Saying the same again does nothing. | | |
| 444 | 453 | | `g1t session end` | Ends it, with an optional `--reason` and `--result` (what it reported; `-` reads it from stdin), and forgets it. Its subagents still going end with it. | | |
| 445 | − | | `g1t session list` | The repository's sessions; `--state active`, `--issue`, `--pull` (any session tied to it), `--path` (those that touched a file, or a folder ending in `/`), `--subagents` to list subagents under the sessions that started them. | | |
| 446 | − | | `g1t session view [ID]` | A session and what it recorded, its subagents and their results, the issues and pull requests it worked on, and the skills used; the current one without an id. | | |
| 454 | + | | `g1t session list` | The repository's sessions; `--state active`, `--item`, `--pull` (any session tied to it), `--path` (those that touched a file, or a folder ending in `/`), `--subagents` to list subagents under the sessions that started them. | | |
| 455 | + | | `g1t session view [ID]` | A session and what it recorded, its subagents and their results, the work items and pull requests it worked on, and the skills used; the current one without an id. | | |
| 447 | 456 | ||
| 448 | 457 | The id is kept in `.git/g1t/session`, in the working copy's own git | |
| 449 | 458 | directory, so each worktree has its own. `G1T_SESSION` overrides it, for | |
| ⋯ | |||
| 452 | 461 | ### Claims and context | |
| 453 | 462 | ||
| 454 | 463 | ```sh | |
| 455 | − | g1t work context 12 # everything about #12's work | |
| 464 | + | g1t work view 12 # everything about #12's work | |
| 456 | 465 | g1t work claim 12 --note "Taking the parser" --ttl 1h | |
| 457 | 466 | g1t work claim --title "Preview builds time out" --body "Over 1 GB, the build stops at 10 minutes." | |
| 458 | 467 | g1t work release 12 --reason done | |
| 459 | 468 | g1t work handoff 12 --to ana --note "Parser done; lexer tests still fail." | |
| 460 | − | g1t work list # active claims and sessions here | |
| 469 | + | g1t work status # active claims and sessions here | |
| 461 | 470 | ``` | |
| 462 | 471 | ||
| 463 | − | `g1t work context` is the one call to make before starting: the issue and | |
| 464 | − | its definition of done, who has claimed it, its sessions, its pull | |
| 472 | + | `g1t work view` is the one call to make before starting: the work item and | |
| 473 | + | its definition of done, its repositories with their roles and which have | |
| 474 | + | landed, who has claimed it, its sessions, its pull | |
| 465 | 475 | requests with their checks, overlaps and place in the merge queue, what it | |
| 466 | 476 | waits on and what waits on it, its decisions, its last integration failure | |
| 467 | 477 | and its recent events. | |
| 468 | 478 | ||
| 469 | − | `g1t work claim` says you are working on an issue. It lasts 30 minutes | |
| 479 | + | `g1t work claim` says you are working on a work item. It lasts 30 minutes | |
| 470 | 480 | unless `--ttl` says otherwise (at most `4h`), and a heartbeat of the session | |
| 471 | 481 | it was made in renews it. It is made in the current session, if there is | |
| 472 | − | one. If others have claimed the issue too, or it waits on issues that are | |
| 473 | − | not done, the answer says so. `g1t work handoff` ends your claim and asks | |
| 474 | − | `--to` someone, or anyone without it, to take the issue over, with a | |
| 482 | + | one. If others have claimed the work item too, or it waits on work items | |
| 483 | + | that are not done, the answer says so. `g1t work handoff` ends your claim and asks | |
| 484 | + | `--to` someone, or anyone without it, to take the work item over, with a | |
| 475 | 485 | `--note` saying where it stands. Claims, releases and hand-offs are the | |
| 476 | 486 | current session's, so two sessions of yours (sibling subagents) each hold | |
| 477 | 487 | their own. | |
| 478 | 488 | ||
| 479 | − | For work that has no issue yet, `g1t work claim --title "…"` (with | |
| 480 | − | `--body` for its description) opens the issue and claims it in one step, | |
| 481 | − | and attaches the current session to it; it prints the new issue's number. | |
| 482 | − | Use it once the work is a change others should know about, after looking | |
| 483 | − | for an issue that already covers it; questions, exploration and trivial | |
| 489 | + | For work that has no work item yet, `g1t work claim --title "…"` (with | |
| 490 | + | `--body` for its description) opens the work item, with the current | |
| 491 | + | repository as its origin, and claims it in one step, and attaches the | |
| 492 | + | current session to it; it prints the new work item's number. Use it once | |
| 493 | + | the work is a change others should know about, after looking for a work | |
| 494 | + | item that already covers it; questions, exploration and trivial | |
| 484 | 495 | fixes need none. A number and `--title` together are refused. | |
| 485 | 496 | ||
| 486 | − | ### Starting a session on an issue | |
| 497 | + | ### Starting a session on a work item | |
| 487 | 498 | ||
| 488 | 499 | ```sh | |
| 489 | 500 | g1t work dispatch 12 # on the workspace's Anthropic account | |
| 490 | 501 | g1t work dispatch 12 --mode plan --instruction "Keep the old flag" | |
| 491 | − | g1t work dispatch --title "Add a healthcheck" --handoff # open the issue; print a claude command | |
| 502 | + | g1t work dispatch --title "Add a healthcheck" --handoff # open the work item; print a claude command | |
| 492 | 503 | ``` | |
| 493 | 504 | ||
| 494 | − | `g1t work dispatch` starts work on an issue in a session on your own | |
| 505 | + | `g1t work dispatch` starts work on a work item in a session on your own | |
| 495 | 506 | Claude: with the workspace's Anthropic [AI provider](/guides/ai/), a Claude Managed Agents | |
| 496 | 507 | session on that account (it prints the session's page on g1t); without | |
| 497 | 508 | one, or with `--handoff`, the `claude` command line to run in your working | |
| ⋯ | |||
| 499 | 510 | `--managed` fails rather than hand off. `--mode` is `plan`, `implement` or | |
| 500 | 511 | `review`. See [Start a session on your Anthropic account](/guides/sessions/#start-a-session-on-your-anthropic-account). | |
| 501 | 512 | ||
| 502 | − | `g1t issue edit 12 --add-assignee g1t` does the same as **Assign to g1t** | |
| 503 | − | on the site: g1t starts a session on the issue on the workspace's | |
| 513 | + | `g1t work edit 12 --add-assignee g1t` does the same as **Assign to g1t** | |
| 514 | + | on the site: g1t starts a session on the work item on the workspace's | |
| 504 | 515 | Anthropic account, as you. See | |
| 505 | 516 | [Assign g1t](/guides/sessions/#assign-g1t-or-ask-it-in-the-thread). | |
| 506 | 517 | ||
| ⋯ | |||
| 511 | 522 | g1t work unblock 12 --by 9 | |
| 512 | 523 | ``` | |
| 513 | 524 | ||
| 514 | − | These change the issue's `blocked_by` through `update_issue`. An issue | |
| 515 | − | cannot wait on itself, and g1t refuses a cycle. | |
| 525 | + | These change the work item's `blocked_by` through `update_work_item`. A | |
| 526 | + | work item waits only on work items of its workspace, never on itself, and | |
| 527 | + | g1t refuses a cycle. | |
| 516 | 528 | ||
| 517 | 529 | ### Following events | |
| 518 | 530 | ||
| ⋯ | |||
| 521 | 533 | a public address, until you stop it with Ctrl-C: | |
| 522 | 534 | ||
| 523 | 535 | ```sh | |
| 524 | − | g1t work events --follow --issue 12 | |
| 536 | + | g1t work events --follow --item 12 | |
| 525 | 537 | g1t work events --follow --type integration.failed --type overlap.detected --json | |
| 526 | 538 | ``` | |
| 527 | 539 | ||
| 528 | 540 | | Flag | | | |
| 529 | 541 | | --- | --- | | |
| 530 | 542 | | `--type`, `-t` | Only events of this type, such as `work.claimed`; repeat for more. | | |
| 531 | − | | `--issue`, `-i` | Only events about this issue or pull request; repeat for more. | | |
| 543 | + | | `--item`, `-i` | Only events about this work item or pull request; repeat for more. | | |
| 532 | 544 | | `--since`, `-s` | Only events since then: `15m`, `2h`, `1d`, or an RFC 3339 time. | | |
| 533 | 545 | | `--after` | Start after this event id, to resume where an earlier follow stopped. | | |
| 534 | 546 | | `--limit`, `-L` | How many past events to show first; 20 by default. | | |
| 535 | 547 | ||
| 536 | − | Each event is one line: its time, type, issue or pull request, a summary | |
| 548 | + | Each event is one line: its time, type, work item or pull request, a summary | |
| 537 | 549 | and its id. With `--json`, each is one compact JSON object on a line of its | |
| 538 | 550 | own, so a program can read them as they come. Following asks | |
| 539 | 551 | [`list_events`](/reference/api/repositories/list-events/) with `after` and | |
| ⋯ | |||
| 549 | 561 | ``` | |
| 550 | 562 | ||
| 551 | 563 | `g1t why` follows a line to the commit that last changed it, the pull | |
| 552 | − | request that merged that commit, the issue the pull request was for, and | |
| 564 | + | request that merged that commit, the work item the pull request was for, and | |
| 553 | 565 | the decisions and sessions recorded on them. A path is read from where you | |
| 554 | 566 | are in the working copy. | |
| 555 | 567 | ||
| ⋯ | |||
| 620 | 632 | with your token, and fills the repository in from where you are: | |
| 621 | 633 | ||
| 622 | 634 | ```sh | |
| 623 | − | g1t api list_issues -f state=closed --jq '.[].title' | |
| 635 | + | g1t api list_work_items -f state=closed --jq '.[].title' | |
| 624 | 636 | g1t api create_label -f name=p1 -f color=d73a4a | |
| 625 | 637 | g1t api get_workflow_run -f id=run_01kpx7b3c6d9e2f5g8h1j4k7mr | |
| 626 | 638 | g1t api --list label # the operations about labels | |
| ⋯ | |||
| 629 | 641 | A path works too, with `{owner}`, `{name}` and `{workspace}` filled in: | |
| 630 | 642 | ||
| 631 | 643 | ```sh | |
| 632 | − | g1t api /repos/{owner}/{name}/labels | |
| 644 | + | g1t api /workspaces/{workspace}/labels | |
| 633 | 645 | g1t api user --jq .username | |
| 634 | 646 | ``` | |
| 635 | 647 | ||
| ⋯ | |||
| 660 | 672 | `AGENTS.md` are enough: | |
| 661 | 673 | ||
| 662 | 674 | ```md | |
| 663 | − | This repository is on g1t. Use the `g1t` CLI for issues, pull requests, | |
| 675 | + | This repository is on g1t. Use the `g1t` CLI for work items, pull requests, | |
| 664 | 676 | checks and runs; add `--json` to read results, and see `g1t <command> --help`. | |
| 665 | 677 | ||
| 666 | − | - Open a pull request: `g1t pr create --fill --issue <n>` | |
| 678 | + | - Open a pull request: `g1t pr create --fill --item <n>` | |
| 667 | 679 | - Wait for checks: `g1t pr checks --watch --fail-fast` (exit 0 passed, 1 failed) | |
| 668 | 680 | - See why a run failed: `g1t run logs --failed` | |
| 669 | 681 | - Run a workflow by hand: `g1t workflow run <file> -f key=value` | |
| ⋯ | |||
| 681 | 693 | arguments after it, and the rest go on the end: | |
| 682 | 694 | ||
| 683 | 695 | ```sh | |
| 684 | − | g1t alias set bugs 'issue list --label bug' | |
| 696 | + | g1t alias set bugs 'work list --label bug' | |
| 685 | 697 | g1t alias set co 'pr checkout' | |
| 686 | 698 | g1t alias set mine '!g1t pr list --author @me --json number,title' | |
| 687 | 699 | g1t bugs --limit 5 | |
| 264 | 264 | When a required check fails (or, on a branch with no required checks, a | |
| 265 | 265 | workflow's status fails), the pull request stays open with its failing | |
| 266 | 266 | checks for you to decide on: push the code changes the update needs to its | |
| 267 | − | branch, or close it. g1t opens no issue for it. Security updates are | |
| 267 | + | branch, or close it. g1t opens no work item for it. Security updates are | |
| 268 | 268 | handled [the same way](/guides/security/#when-an-update-cannot-be-made). | |
| 269 | 269 | ||
| 270 | 270 | If the sandbox has not pushed a branch 45 minutes after an update started, |
| 10 | 10 | it. | |
| 11 | 11 | ||
| 12 | 12 | Fork a repository to contribute to one you cannot push to, or to start your | |
| 13 | − | own line of work from someone else's code. To work on an issue in a | |
| 13 | + | own line of work from someone else's code. To work on a work item in a | |
| 14 | 14 | repository you can already write to, you do not need a fork: open a pull | |
| 15 | 15 | request from a branch, or let it [make a working copy](/concepts/forks/#working-copies-for-pull-requests). | |
| 16 | 16 | ||
| ⋯ | |||
| 69 | 69 | ||
| 70 | 70 | | Copied | Not copied | | |
| 71 | 71 | | --- | --- | | |
| 72 | − | | The default branch, or every branch and tag | Issues, pull requests, comments and labels | | |
| 72 | + | | The default branch, or every branch and tag | Work items, pull requests and comments | | |
| 73 | 73 | | Its project's description, to the fork's project | Settings, rulesets and branch protection | | |
| 74 | 74 | | | Secrets, variables and webhooks | | |
| 75 | 75 | | | Environments, projects, deployments and custom domains | | |
| 76 | 76 | | | Releases, packages and stars | | |
| 77 | 77 | ||
| 78 | − | Issues are off in a new fork, and so are its workflows: a fork runs none of | |
| 78 | + | Filing work items is off in a new fork, and so are its workflows: a fork runs none of | |
| 79 | 79 | the workflows it copied until someone turns them on (see | |
| 80 | 80 | [Turn on workflows](#turn-on-workflows)). Deployments stay off until you set | |
| 81 | 81 | up the fork's own project. | |
| ⋯ | |||
| 227 | 227 | ||
| 228 | 228 | A detached fork keeps its code, settings and the pull requests it already | |
| 229 | 229 | opened into the parent, which stay open there. It can no longer be synced or | |
| 230 | − | open new pull requests into the parent, and its workflows and issues stay | |
| 230 | + | open new pull requests into the parent, and its workflows and work items stay | |
| 231 | 231 | off unless someone had turned them on. It cannot be attached again. | |
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Comments
Sign in to comment.