| 1 | --- |
| 2 | title: How g1t works |
| 3 | description: How Code works on g1t, and how issues, pull requests, checks, review, merging and sessions fit together. |
| 4 | --- |
| 5 | |
| 6 | g1t is where a team's code, conversations and shipping live. A workspace |
| 7 | holds your repositories, with issues, pull requests, required checks and |
| 8 | the merge queue; [Actions](/guides/actions/) that run your workflows; |
| 9 | [Deployments](/guides/deployments/) that put every pull request live; |
| 10 | and [Chat](/guides/chat/) and [Artifacts](/guides/artifacts/) for your |
| 11 | team. This page is about **Code**, where changes are made and landed. |
| 12 | |
| 13 | The coding agents you already use, such as Claude Code, Codex, Cursor or |
| 14 | OpenCode, work on g1t from wherever they run. They connect over |
| 15 | [MCP](/guides/bring-your-own-agent/), the [REST API](/reference/api/) and |
| 16 | [webhooks](/guides/webhooks/), act as the person who connected them, and |
| 17 | go through the same pull requests, checks, reviews and rules as everyone |
| 18 | else. |
| 19 | |
| 20 | Underneath it is ordinary git: repositories, commits, branches, clone, push |
| 21 | and pull all work as they do anywhere. On top of that it has the two things |
| 22 | you already know, **issues** and **pull requests**, built |
| 23 | so that many people and agents can work at once without getting in each |
| 24 | other's way. |
| 25 | |
| 26 | | | What it is | |
| 27 | | --- | --- | |
| 28 | | **Issue** | What should change: a bug, a feature, a question. | |
| 29 | | **Pull request** | A proposed change, in its own fork or on a branch. Usually made for an issue. | |
| 30 | | **Session** | The record of how a pull request was made, written by the coding agent that made it: prompts, reasoning, tool calls. | |
| 31 | |
| 32 | What g1t adds: one issue can have several pull requests, each from a |
| 33 | different person or agent, and g1t keeps track of which one was merged. |
| 34 | |
| 35 | ## Issues |
| 36 | |
| 37 | An issue says what should change in a repository. People open them, coding |
| 38 | agents open them, and so can anything with an access token, such as an error |
| 39 | tracker reporting a crash. |
| 40 | |
| 41 | An issue has: |
| 42 | |
| 43 | - a **title** and a **description** in Markdown. Whoever works on the |
| 44 | issue, person or agent, works from this text. It can say what done means |
| 45 | in plain words, under a `## Definition of done` heading if you like: |
| 46 | context for whoever works on it and its reviewers, not something a merge |
| 47 | waits on; |
| 48 | - **labels**, which say what kind of issue it is; |
| 49 | - **comments**; |
| 50 | - a **state**: open or closed. A closed issue records why: `completed` or |
| 51 | `not_planned`. |
| 52 | |
| 53 | Issues and pull requests share one sequence of numbers per repository, so |
| 54 | `#12` names exactly one of them. |
| 55 | |
| 56 | ### Labels |
| 57 | |
| 58 | Every repository starts with `bug`, `feature`, `docs`, `chore` and |
| 59 | `question`. There is nothing to set up for others: putting a new name on an |
| 60 | issue creates the label. Labels are lowercase, and an issue can carry up to |
| 61 | ten. |
| 62 | |
| 63 | Filter a repository's issues by label on the site, or with `?label=` in the |
| 64 | API. |
| 65 | |
| 66 | ## Pull requests |
| 67 | |
| 68 | A pull request is a proposed change. There are two ways to make one. |
| 69 | |
| 70 | **In a fork.** This is how coding agents usually work: the `pull_request` |
| 71 | tool's `create` action opens one for an issue. Opening the pull request creates a |
| 72 | copy of the repository that belongs to that pull request alone, ready in |
| 73 | about the time a branch would be. Its author clones the fork, commits and pushes to it. Nothing they do |
| 74 | can touch `main` or another pull request. The fork lives at |
| 75 | `g1t.sh/pulls/<pull request id>.git` and is exactly as visible as the |
| 76 | repository it came from. The pull request starts as a draft. |
| 77 | |
| 78 | **From a branch.** This is the way you already know. Push a branch to the |
| 79 | repository, then open a pull request from it on the **Pull requests** tab. |
| 80 | It needs write access to the repository, and it is ready for review as soon |
| 81 | as it is opened. |
| 82 | |
| 83 | [Forks and branches](/concepts/forks/) explains when each is the better |
| 84 | choice. |
| 85 | |
| 86 | | Status | Meaning | |
| 87 | | --- | --- | |
| 88 | | `draft` | Still being worked on. A pull request with a fork starts here. | |
| 89 | | `open` | Ready for review, with a description of what changed and why. | |
| 90 | | `merged` | Landed on `main`. | |
| 91 | | `closed` | Closed without merging. | |
| 92 | |
| 93 | A pull request is normally opened **for an issue**. It can also stand alone, |
| 94 | with its own title, for a change nobody filed an issue about. |
| 95 | |
| 96 | ## Assignees and reviewers |
| 97 | |
| 98 | An issue is assigned to people. A pull request has assignees too, and |
| 99 | reviewers: the people whose review was asked for. Each shows beside the |
| 100 | conversation, with where every reviewer stands. |
| 101 | |
| 102 | Whatever happens is told in the conversation, in order, between the |
| 103 | comments: who assigned whom, whose review was asked for, and when it was |
| 104 | marked ready, merged or closed. |
| 105 | |
| 106 | ## Several pull requests for one issue |
| 107 | |
| 108 | An issue can have more than one pull request: a second attempt after the |
| 109 | first fell short, or two agents trying different approaches. Each is in its own |
| 110 | fork, with its own session and its own diff. The issue's page lists them |
| 111 | all with their status. |
| 112 | |
| 113 | When you merge one: |
| 114 | |
| 115 | - the pull request becomes `merged`, recording who merged it and when; |
| 116 | - the issue closes as `completed`, and records that pull request as the one |
| 117 | that **resolved** it; |
| 118 | - every other pull request for that issue that was still a draft or open is |
| 119 | closed, marked as **superseded** by the one that was merged. |
| 120 | |
| 121 | So the answer to "which one did we take?" is on the issue, on the merged |
| 122 | pull request, and on each one that was passed over. |
| 123 | |
| 124 | Sometimes several pull requests each do part of an issue. When merging, say |
| 125 | that the issue should stay open. The pull request merges, and the issue and |
| 126 | the other pull requests are left as they are. |
| 127 | |
| 128 | ## Checks |
| 129 | |
| 130 | A pull request's checks are what the repository's |
| 131 | [workflows](/guides/actions/) report on its head commit. Every workflow |
| 132 | that runs on `pull_request` runs on every pull request, whoever opened it, |
| 133 | a person or an agent, and reports a check named after the workflow, such as |
| 134 | `CI`. |
| 135 | |
| 136 | The default branch decides which checks a merge needs: its |
| 137 | [required status checks](/guides/pull-requests/#required-status-checks). |
| 138 | A pull request merges only once each of them has passed on its head. One |
| 139 | that failed, is still running or has not reported yet holds the merge, |
| 140 | unless the repository allows bypassing them and someone who can merge |
| 141 | chooses to. Checks that are not required are shown, and never hold a merge. |
| 142 | |
| 143 | The same rules hold for people and agents. A pull request a coding agent |
| 144 | opens is checked by the same workflows as yours, and an agent cannot mark |
| 145 | its own work as passing: only the workflow runs report. |
| 146 | |
| 147 | ## Review |
| 148 | |
| 149 | Anyone who can see a pull request can comment on it, on the whole of it or |
| 150 | on a single line of its change. Line comments are shown in the **Files changed** |
| 151 | tab under the line they are about. |
| 152 | |
| 153 | A reviewer can also give a verdict: **approve**, or **request changes**. |
| 154 | The pull request shows where each reviewer stands. You cannot give a verdict |
| 155 | on a pull request you opened, and that holds for a coding agent working as |
| 156 | you too. |
| 157 | |
| 158 | ## Overlap |
| 159 | |
| 160 | When many changes are in flight, some touch the same files. g1t keeps track |
| 161 | of which files each pull request changes, from every push, and shows on a |
| 162 | pull request which others in progress change the same ones. |
| 163 | |
| 164 | Two pull requests for the *same* issue are expected to overlap: they are |
| 165 | alternatives, and one will be merged. Two for *different* issues are heading |
| 166 | for a conflict, and g1t says so while the work is still going on rather than |
| 167 | when the second one tries to merge. Coding agents get the same list from |
| 168 | the `pull_request` tool's `get` action, as `overlaps`, so they can keep |
| 169 | their edits small and local where they have to touch the same files. |
| 170 | |
| 171 | ## Merging |
| 172 | |
| 173 | Someone with the [Write role](/guides/access-and-roles/) or higher on the |
| 174 | repository merges a pull request once it is |
| 175 | marked ready and its [required checks](/guides/pull-requests/#required-status-checks) |
| 176 | have passed. Merging moves `main` to the pull |
| 177 | request's head commit, or, in a repository that merges through |
| 178 | [the merge queue](/guides/merge-queue/), adds it to the queue. |
| 179 | |
| 180 | `main` only moves forward to a commit that contains everything already on |
| 181 | it. If something else landed first, the pull request is **behind**, and its |
| 182 | page says so. Merging it then brings it up to date first and lands it once |
| 183 | that is done, unless the repository requires pull requests to be up to date |
| 184 | before they merge; then merging is refused until it has caught up. |
| 185 | |
| 186 | **Catch up with main** brings it up to date. When the pull request and `main` changed |
| 187 | different files, g1t merges `main` in itself and pushes the merge in a few |
| 188 | seconds, and the workflows run again on the result |
| 189 | ([how catching up works](/guides/pull-requests/#catching-up)). When they |
| 190 | changed some of the same files, do it by hand: pull `main` into the fork or |
| 191 | the branch, resolve, and push. `main` never loses a commit this way, however many |
| 192 | pull requests are in flight. |
| 193 | |
| 194 | ## The merge queue |
| 195 | |
| 196 | Merging one pull request at a time keeps every merge clean as text, but two |
| 197 | changes can merge without a conflict and still break each other. A |
| 198 | repository whose rules include **Require the merge queue** (**Settings → |
| 199 | Rules**) tests each pull request |
| 200 | together with the ones ahead of it, and `main` only moves to a state whose |
| 201 | required checks passed. |
| 202 | See [merge queue](/guides/merge-queue/). |
| 203 | |
| 204 | ## Sessions and why-blame |
| 205 | |
| 206 | A session is the record of how a pull request was made: the prompt the |
| 207 | agent was given, its reasoning, the tools it called and what they returned. |
| 208 | The coding agent records it with the `pull_request` tool's `record_session` |
| 209 | action as it works. |
| 210 | Each entry is tied to the commit that was the head when it was recorded, so |
| 211 | **Blame** on any file can show not only the commit that last changed a |
| 212 | line, but the pull request and issue it came from and the agent's own |
| 213 | account of the change. See [sessions and why-blame](/guides/why-blame/). |
| 214 | |
| 215 | ## Events |
| 216 | |
| 217 | Every state change in g1t is published as an event: a push, an issue being |
| 218 | opened, a pull request being merged, a session growing. Events are delivered |
| 219 | to the services that react to them and are kept as a timeline per |
| 220 | repository, which you can read through the [API](/reference/api/). |
| 221 | [Events](/architecture/events/) in the Architecture section shows how. |
| 222 | |
| 223 | ## What is not built yet |
| 224 | |
| 225 | g1t is under active development. Every current limit, and why, is on |
| 226 | [What g1t can't do yet](/about/limitations/). |