| 1 | --- |
| 2 | title: How g1t works |
| 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 | --- |
| 5 | |
| 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 |
| 9 | workflows; [Deployments](/guides/deployments/) that put every pull request |
| 10 | live; and [Chat](/guides/chat/) for your team. This page is about |
| 11 | **Code**, where changes are made and landed. |
| 12 | |
| 13 | Underneath is ordinary git: clone, branch, commit, push and pull work as |
| 14 | they do anywhere. On top of it are the two things you already know, |
| 15 | **work items** and **pull requests**, built so that many people and coding |
| 16 | agents can work at once without getting in each other's way. |
| 17 | |
| 18 | The coding agents you already use, such as Claude Code, Codex, Cursor or |
| 19 | OpenCode, work on g1t from wherever they run. They connect over |
| 20 | [MCP](/guides/bring-your-own-agent/), the [g1t CLI](/guides/cli/), the |
| 21 | [REST API](/reference/api/) and [webhooks](/guides/webhooks/), act as the |
| 22 | person who connected them, and go through the same pull requests, checks, |
| 23 | reviews and rules as everyone else. |
| 24 | |
| 25 | | | What it is | |
| 26 | | --- | --- | |
| 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. | |
| 30 | |
| 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. |
| 34 | |
| 35 | ## Work items |
| 36 | |
| 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/). |
| 41 | |
| 42 | A work item has: |
| 43 | |
| 44 | - a **title** and a **description** in Markdown. Whoever works on the |
| 45 | work item, person or agent, works from this text. Say what done means in |
| 46 | plain words, under a `## Definition of done` heading if you like: it is |
| 47 | context for whoever works on it and its reviewers, not something a merge |
| 48 | waits on; |
| 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; |
| 53 | - **comments** and **assignees**; |
| 54 | - a **state**: open or closed. A closed work item records why: |
| 55 | `completed` or `not_planned`. |
| 56 | |
| 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. |
| 59 | |
| 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/). |
| 64 | |
| 65 | ## Pull requests |
| 66 | |
| 67 | A pull request is a proposed change. There are two ways to make one. |
| 68 | |
| 69 | **From a branch.** Push a branch to the repository, then open a pull |
| 70 | request from it on the **Pull requests** tab or with `g1t pr create`. It |
| 71 | needs write access to the repository, and is ready for review as soon as |
| 72 | it is opened. |
| 73 | |
| 74 | **In a working copy.** This is how coding agents usually work: the |
| 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 |
| 78 | it a copy of the repository that belongs to that pull request alone, |
| 79 | ready in about the time a branch would be. The author clones it, commits |
| 80 | and pushes to it, and nothing they do can touch `main` or another pull |
| 81 | request. It lives at `g1t.sh/pulls/<pull request id>.git` and is exactly |
| 82 | as visible as the repository it came from. |
| 83 | |
| 84 | [Forks and working copies](/concepts/forks/) explains when each is the |
| 85 | better choice. |
| 86 | |
| 87 | | Status | Meaning | |
| 88 | | --- | --- | |
| 89 | | `draft` | Still being worked on. A pull request in a working copy starts here. | |
| 90 | | `open` | Ready for review, with a description of what changed and why. | |
| 91 | | `merged` | Landed on its base branch. | |
| 92 | | `closed` | Closed without merging. | |
| 93 | |
| 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. |
| 96 | |
| 97 | ## Assignees and reviewers |
| 98 | |
| 99 | Work items and pull requests have assignees, and pull requests have |
| 100 | reviewers: the people and teams whose review was asked for. Each shows |
| 101 | beside the conversation, with where every reviewer stands. |
| 102 | |
| 103 | Assigning a work item to `g1t`, or mentioning `@g1t` in a comment, starts a |
| 104 | session on the workspace's own Anthropic account, as the person who asked; |
| 105 | see [Assign g1t](/guides/sessions/#assign-g1t-or-ask-it-in-the-thread). |
| 106 | |
| 107 | The conversation tells what happened, in order, between the comments: who |
| 108 | assigned whom, whose review was asked for, which sessions started, and |
| 109 | when it was marked ready, merged or closed. |
| 110 | |
| 111 | ## Several pull requests for one work item |
| 112 | |
| 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. |
| 118 | |
| 119 | When you merge one: |
| 120 | |
| 121 | - the pull request becomes `merged`, recording who merged it and when; |
| 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. |
| 129 | |
| 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. |
| 132 | |
| 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. |
| 137 | |
| 138 | ## Checks |
| 139 | |
| 140 | A pull request's checks are what the repository's |
| 141 | [workflows](/guides/actions/) and integrations report on its head commit. |
| 142 | Every workflow that runs on `pull_request` runs on every pull request, |
| 143 | whoever opened it, and reports a check named after the workflow, such as |
| 144 | `CI`. |
| 145 | |
| 146 | The base branch decides which checks a merge needs: its |
| 147 | [required status checks](/guides/pull-requests/#required-status-checks). |
| 148 | A pull request merges only once each of them has passed on its head. One |
| 149 | that failed, is still running or has not reported yet holds the merge, |
| 150 | unless the repository allows bypassing them and someone who can merge |
| 151 | chooses to. Checks that are not required are shown, and never hold a merge. |
| 152 | |
| 153 | The same rules hold for people and agents. A pull request an agent opens |
| 154 | is checked by the same workflows as yours, and an agent cannot mark its |
| 155 | own work as passing: only the checks report. |
| 156 | |
| 157 | ## Review |
| 158 | |
| 159 | Anyone who can see a pull request can comment on it, on the whole of it or |
| 160 | on a single line of its change, in **Files changed**. |
| 161 | |
| 162 | A reviewer can also give a verdict: **approve**, or **request changes**. |
| 163 | You cannot give a verdict on a pull request you opened, and neither can a |
| 164 | coding agent working as you. |
| 165 | |
| 166 | ## Overlap |
| 167 | |
| 168 | When many changes are in flight, some touch the same files. g1t tracks |
| 169 | which files each pull request changes, from every push, and shows on a |
| 170 | pull request which others in progress change the same ones. |
| 171 | |
| 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 |
| 175 | heading for a conflict, and g1t says so while the work is still going on, |
| 176 | not when the second one tries to merge. Agents get the same list from the |
| 177 | `pull_request` tool's `get` action, as `overlaps`, so they can keep their |
| 178 | edits small where they must touch the same files. |
| 179 | |
| 180 | ## Merging |
| 181 | |
| 182 | Someone with the [Write role](/guides/access-and-roles/) or higher merges |
| 183 | a pull request once it is ready and its |
| 184 | [required checks](/guides/pull-requests/#required-status-checks) have |
| 185 | passed. It lands by one of the repository's |
| 186 | [merge methods](/guides/pull-requests/#merge-methods): a merge commit, a |
| 187 | squash, a rebase or a fast-forward. In a repository that uses |
| 188 | [the merge queue](/guides/merge-queue/), merging adds it to the queue |
| 189 | instead. **Auto-merge** lands it by itself once everything it needs is met. |
| 190 | |
| 191 | When something else landed first, the pull request is **behind**, and its |
| 192 | page says so. Merging brings it up to date and lands it, unless the |
| 193 | repository requires pull requests to be up to date first; then merging |
| 194 | waits until it has caught up. |
| 195 | |
| 196 | **Update branch** brings it up to date. When the two sides' changes do |
| 197 | not clash (edits to the same file merge line by line), g1t merges or |
| 198 | rebases the base in itself in a few seconds, and the workflows run again |
| 199 | ([keeping it up to date](/guides/pull-requests/#keeping-it-up-to-date)). |
| 200 | When they changed the same lines, pull the base into the branch or |
| 201 | working copy, resolve, and push. The base never loses a commit this way, |
| 202 | however many pull requests are in flight. |
| 203 | |
| 204 | ## The merge queue |
| 205 | |
| 206 | Merging one pull request at a time keeps every merge clean as text, but |
| 207 | two changes can merge without a conflict and still break each other. A |
| 208 | repository whose rules include **Require the merge queue** (**Settings → |
| 209 | Rules**) tests each pull request together with the ones ahead of it, and |
| 210 | the base only moves to a state whose required checks passed. When one |
| 211 | fails in combination, g1t says which pull requests and which check, so its |
| 212 | author, person or agent, can fix it. See [merge queue](/guides/merge-queue/). |
| 213 | |
| 214 | ## Sessions and why-blame |
| 215 | |
| 216 | A session is one run of a coding agent: the prompts it was given, its |
| 217 | reasoning, the tools it called, and what it touched. g1t's |
| 218 | [Claude Code plugin](/guides/claude-code-plugin/) records one for every |
| 219 | Claude Code session in a g1t repository; other agents record theirs with |
| 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 |
| 225 | [sessions, claims and dependencies](/guides/sessions/). |
| 226 | |
| 227 | Each entry is tied to the commit that was the head when it was recorded, |
| 228 | so **Blame** on any file can show not only the commit that last changed a |
| 229 | line, but the pull request and work item it came from and the agent's own |
| 230 | account of the change. See [sessions and why-blame](/guides/why-blame/). |
| 231 | |
| 232 | ## Events |
| 233 | |
| 234 | Every state change in g1t is published as an event: a push, a work item being |
| 235 | opened, a pull request being merged, a session growing. Events reach the |
| 236 | services that react to them, your [webhooks](/guides/webhooks/), and a |
| 237 | timeline per repository that you can read through the |
| 238 | [API](/reference/api/) or follow with `g1t work events --follow`. |
| 239 | [Events](/architecture/events/) in the Architecture section shows how. |
| 240 | |
| 241 | ## What is not built yet |
| 242 | |
| 243 | Every current limit, and why, is on |
| 244 | [What g1t can't do yet](/about/limitations/). |