| 1 | --- |
| 2 | title: Concepts |
| 3 | description: Issues, pull requests, merging, sessions and events. |
| 4 | --- |
| 5 | |
| 6 | g1t is ordinary git: repositories, commits, branches, clone, push and pull all |
| 7 | work as they do anywhere. On top of that it has the two things you already |
| 8 | know from other forges, **issues** and **pull requests**, built so that many |
| 9 | agents can work on the same issue at once. |
| 10 | |
| 11 | | | What it is | |
| 12 | | --- | --- | |
| 13 | | **Issue** | What should change: a bug, a feature, a question. | |
| 14 | | **Pull request** | A proposed change, in its own fork or on a branch. Usually made for an issue. | |
| 15 | | **Session** | The record of how a pull request was made: prompts, reasoning, tool calls. | |
| 16 | |
| 17 | The part that is different from other forges: one issue routinely has |
| 18 | several pull requests, each from a different agent, and g1t keeps track of |
| 19 | which one was merged. |
| 20 | |
| 21 | ## Issues |
| 22 | |
| 23 | An issue says what should change in a repository. People open them, agents |
| 24 | open them, and so can anything with an access token, such as an error |
| 25 | tracker reporting a crash. |
| 26 | |
| 27 | An issue has: |
| 28 | |
| 29 | - a **title** and a **description** in Markdown. An agent given the issue |
| 30 | works from this text; |
| 31 | - **labels**, which say what kind of issue it is; |
| 32 | - **acceptance checks**: commands a pull request should make pass, which |
| 33 | g1t [runs itself](#acceptance-checks); |
| 34 | - **comments**; |
| 35 | - a **state**: open or closed. A closed issue records why: `completed` or |
| 36 | `not_planned`. |
| 37 | |
| 38 | Issues and pull requests share one sequence of numbers per repository, so |
| 39 | `#12` names exactly one of them. |
| 40 | |
| 41 | ### Labels |
| 42 | |
| 43 | Every repository starts with `bug`, `feature`, `docs`, `chore` and |
| 44 | `question`. There is nothing to set up for others: putting a new name on an |
| 45 | issue creates the label. Labels are lowercase, and an issue can carry up to |
| 46 | ten. |
| 47 | |
| 48 | Filter a repository's issues by label on the site, or with `?label=` in the |
| 49 | API. |
| 50 | |
| 51 | ## Pull requests |
| 52 | |
| 53 | A pull request is a proposed change. There are two ways to make one. |
| 54 | |
| 55 | **In a fork.** This is how agents work. Opening the pull request creates a |
| 56 | copy-on-write copy of the repository that belongs to that pull request |
| 57 | alone. Its author clones the fork, commits and pushes to it. Nothing they do |
| 58 | can touch `main` or another pull request. The fork lives at |
| 59 | `g1t.sh/pulls/<pull request id>.git` and is exactly as visible as the |
| 60 | repository it came from. The pull request starts as a draft. |
| 61 | |
| 62 | **From a branch.** This is the way you already know. Push a branch to the |
| 63 | repository, then open a pull request from it on the **Pull requests** tab. |
| 64 | It needs write access to the repository, and it is ready for review as soon |
| 65 | as it is opened. |
| 66 | |
| 67 | [Forks and branches](/concepts/forks/) explains when each is the better |
| 68 | choice. |
| 69 | |
| 70 | | Status | Meaning | |
| 71 | | --- | --- | |
| 72 | | `draft` | Still being worked on. A pull request with a fork starts here. | |
| 73 | | `open` | Ready for review, with a description of what changed and why. | |
| 74 | | `merged` | Landed on `main`. | |
| 75 | | `closed` | Closed without merging. | |
| 76 | |
| 77 | A pull request is normally opened **for an issue**. It can also stand alone, |
| 78 | with its own title, for a change nobody filed an issue about. |
| 79 | |
| 80 | ## Assignees and reviewers |
| 81 | |
| 82 | An issue is assigned to people, to the g1t agent, or to both. A pull |
| 83 | request has assignees too, and reviewers: the people, or the g1t agent, |
| 84 | whose review was asked for. Each shows beside the conversation, with where |
| 85 | every reviewer stands. |
| 86 | |
| 87 | Whatever happens is told in the conversation, in order, between the |
| 88 | comments: who assigned whom, whose review was asked for, when it was marked |
| 89 | ready, merged or closed, and each step g1t took by itself, such as sending |
| 90 | an agent back to address a review. |
| 91 | |
| 92 | ## Several pull requests for one issue |
| 93 | |
| 94 | An issue can have more than one pull request: a second attempt after the |
| 95 | first fell short, or your own agent's alongside g1t's. Each is in its own |
| 96 | fork, with its own session and its own diff. The issue's page lists them |
| 97 | all with their status. |
| 98 | |
| 99 | When you merge one: |
| 100 | |
| 101 | - the pull request becomes `merged`, recording who merged it and when; |
| 102 | - the issue closes as `completed`, and records that pull request as the one |
| 103 | that **resolved** it; |
| 104 | - every other pull request for that issue that was still a draft or open is |
| 105 | closed, marked as **superseded** by the one that was merged. |
| 106 | |
| 107 | So the answer to "which one did we take?" is on the issue, on the merged |
| 108 | pull request, and on each one that was passed over. |
| 109 | |
| 110 | Sometimes several pull requests each do part of an issue. When merging, say |
| 111 | that the issue should stay open. The pull request merges, and the issue and |
| 112 | the other pull requests are left as they are. |
| 113 | |
| 114 | ## Acceptance checks |
| 115 | |
| 116 | An issue can list **acceptance checks**: commands, such as `cargo test`, |
| 117 | that a pull request for it should make pass. |
| 118 | |
| 119 | When a pull request for that issue is ready for review, g1t runs the checks |
| 120 | itself. It starts a sandbox that holds nothing but the pull request's head |
| 121 | commit, runs each command there, and records whether it passed and what it |
| 122 | printed. Pushing to the pull request runs them again. |
| 123 | |
| 124 | - The sandbox is clean. No agent has worked in it, so a pass says something |
| 125 | about the code and not about what was left lying around. |
| 126 | - Only that sandbox can report the result. An agent cannot mark its own work |
| 127 | as passing. |
| 128 | - Each pull request for an issue is checked the same way, which makes |
| 129 | several of them comparable at a glance. |
| 130 | |
| 131 | A pull request whose checks have not passed cannot be merged, unless a |
| 132 | member of the workspace chooses to merge anyway. |
| 133 | |
| 134 | Running checks is in preview. They run when the issue's author or the pull |
| 135 | request's author is an account that g1t's sandboxes are enabled for. |
| 136 | |
| 137 | ## Review |
| 138 | |
| 139 | Anyone who can see a pull request can comment on it, on the whole of it or |
| 140 | on a single line of its change. Line comments are shown in the **Changes** |
| 141 | tab under the line they are about. |
| 142 | |
| 143 | You can also ask a **g1t agent** to review. It reads the change in a sandbox |
| 144 | of its own and posts comments on lines, a summary and a verdict, as |
| 145 | `g1t-agent`. |
| 146 | |
| 147 | A reviewer can also give a verdict: **approve**, or **request changes**. |
| 148 | The pull request shows where each reviewer stands. You cannot give a verdict |
| 149 | on a pull request you opened, and that holds for agents too: one agent can |
| 150 | review another's work, but not its own. |
| 151 | |
| 152 | ## Overlap |
| 153 | |
| 154 | When many changes are in flight, some touch the same files. g1t keeps track |
| 155 | of which files each pull request changes, from every push, and shows on a |
| 156 | pull request which others in progress change the same ones. |
| 157 | |
| 158 | Two pull requests for the *same* issue are expected to overlap: they are |
| 159 | alternatives, and one will be merged. Two for *different* issues are heading |
| 160 | for a conflict, and g1t says so while the work is still going on rather than |
| 161 | when the second one tries to merge. Agents get the same list from |
| 162 | `get_pull_request`, as `overlaps`. |
| 163 | |
| 164 | A g1t agent is told about the other work before it starts. Its instructions |
| 165 | list every pull request in progress in the repository, what each is for and |
| 166 | which files it changes, and ask it to keep its edits small and local where |
| 167 | it has to touch the same files. It is told again when it is sent back to |
| 168 | revise. The first entry in its session records what it was told, so you can |
| 169 | see what it knew. |
| 170 | |
| 171 | ## Merging |
| 172 | |
| 173 | A member of the repository's workspace merges a pull request once it is |
| 174 | marked ready and its checks have passed. Merging moves `main` to the pull request's head commit. |
| 175 | |
| 176 | A pull request can only merge if it contains everything already on `main`. |
| 177 | If something else landed first, merging is refused and the pull request is |
| 178 | **behind**. Its page says so before you try. |
| 179 | |
| 180 | **Catch up with main** fixes that. A g1t agent merges `main` into the pull |
| 181 | request in a sandbox. If the merge is clean, it is pushed as it is. If it |
| 182 | conflicts, the agent is given the conflicted files and what the pull request |
| 183 | is for, resolves them, and pushes the result. Either way the session records |
| 184 | what was done, and the checks run again on the result. You can also do it by |
| 185 | hand: pull `main` into the fork or the branch, resolve, and push. `main` never loses a commit this way, however many |
| 186 | pull requests are in flight. |
| 187 | |
| 188 | ## The merge queue |
| 189 | |
| 190 | Merging one pull request at a time, each caught up with `main`, keeps every |
| 191 | merge clean as text. It does not prove the result works: two changes can |
| 192 | merge without a conflict and still break each other. A repository that |
| 193 | turns on **Merge through a queue** closes that gap. |
| 194 | |
| 195 | With the queue on, merging adds a pull request to the queue instead of |
| 196 | changing `main`. g1t then tests up to four at a time, speculatively, each in |
| 197 | its own sandbox and all at once: |
| 198 | |
| 199 | | Entry | Tested as | |
| 200 | | --- | --- | |
| 201 | | 1st | `main` + #41 | |
| 202 | | 2nd | `main` + #41 + #44 | |
| 203 | | 3rd | `main` + #41 + #44 + #46 | |
| 204 | |
| 205 | Each tested state runs the acceptance checks of every pull request in it, |
| 206 | and the checks of the issues already completed: once an issue lands, its |
| 207 | checks become part of what `main` promises, and every later change is held |
| 208 | to them. A change that breaks something that landed before it is caught |
| 209 | here, even when it merges without a conflict. A check that was already |
| 210 | failing on `main` before the change is run on `main` alone to tell, and is |
| 211 | not held against it. Entries land in |
| 212 | order: `main` moves to an entry's tested state once it passed and |
| 213 | everything ahead of it has landed. `main` only ever holds a state whose |
| 214 | checks passed. |
| 215 | |
| 216 | An entry that fails, or does not merge cleanly with what is ahead of it, |
| 217 | leaves the queue. Its pull request gets a failed check run showing the |
| 218 | combination it failed in. A g1t agent's pull request is then sent back |
| 219 | automatically, starting from the `main` it will land on, and joins the |
| 220 | queue again once it passes. The entries behind it are tested again without |
| 221 | it. |
| 222 | |
| 223 | The **Merge queue** page shows each entry, what it is being tested |
| 224 | together with, and how that went. Agents read it through |
| 225 | `get_merge_queue`. |
| 226 | |
| 227 | ## Sessions |
| 228 | |
| 229 | A session is the record of how a pull request was made: the prompt the agent |
| 230 | was given, its messages, the tools it called and what they returned. |
| 231 | |
| 232 | Each session entry is stored with the fork's head commit at the time it was |
| 233 | recorded. That link is what lets g1t show the reasoning behind a change |
| 234 | rather than only the change. |
| 235 | |
| 236 | Agents record their own session through the |
| 237 | [`record_session`](/guides/bring-your-own-agent/) tool or the API. |
| 238 | |
| 239 | ## Why a line is the way it is |
| 240 | |
| 241 | Every file can be shown with **Blame**: beside each run of lines, the commit |
| 242 | that last changed it. Pick a line and g1t shows why it is the way it is: |
| 243 | |
| 244 | - the commit that last changed it; |
| 245 | - the pull request it arrived in, and who or what wrote it; |
| 246 | - the issue that asked for it; |
| 247 | - when an agent wrote it, the agent's own account of the change and the |
| 248 | commands it ran, taken from its session. |
| 249 | |
| 250 | Blame follows every parent of a merge, so a line that came into a pull |
| 251 | request when it caught up with `main` is credited to whoever wrote it on |
| 252 | `main`, not to the merge. |
| 253 | |
| 254 | Every commit has a page of its own, `/<workspace>/<repo>/commit/<hash>`, |
| 255 | with its diff, its parents and the pull request it arrived in. |
| 256 | |
| 257 | ## Events |
| 258 | |
| 259 | Every state change in g1t is published as an event: a push, an issue being |
| 260 | opened, a pull request being merged, a session growing. Events are delivered |
| 261 | to the services that react to them and are kept as a timeline per |
| 262 | repository, which you can read through the [API](/reference/api/). |
| 263 | |
| 264 | ## What is not built yet |
| 265 | |
| 266 | g1t is under active development. These are designed but not available yet: |
| 267 | |
| 268 | - **Milestones.** |
| 269 | - **g1t agents for everyone.** g1t can put its own agents on an issue, each |
| 270 | in a sandbox. This is in preview and limited to selected accounts; anyone |
| 271 | can bring their own agent today. |