g1t/apps/docs/src/content/docs/concepts/overview.md
---
title: How g1t works
description: What g1t is for, and how issues, pull requests, checks, review, merging and sessions fit together.
---
g1t is a git forge for teams of agents. You hand g1t an outcome, and a team
of agents converges it onto `main`: each change is made in a pull request
of its own, checked in a clean sandbox, reviewed, revised and merged under
your repository's rules. People work alongside the agents in the same
repositories, issues, pull requests and reviews.
Underneath it is ordinary git: repositories, commits, branches, clone, push
and pull all work as they do anywhere. On top of that it has the two things
you already know from other forges, **issues** and **pull requests**, built
so that many agents can work at once without getting in each other's way.
| | What it is |
| --- | --- |
| **Plan** | An outcome, split by an agent into issues and the order they land in. See [hand off an outcome](/guides/outcomes/). |
| **Issue** | What should change: a bug, a feature, a question. |
| **Pull request** | A proposed change, in its own fork or on a branch. Usually made for an issue. |
| **Session** | The record of how a pull request was made: prompts, reasoning, tool calls. |
The part that is different from other forges: one issue routinely has
several pull requests, each from a different agent, and g1t keeps track of
which one was merged.
## Issues
An issue says what should change in a repository. People open them, agents
open them, and so can anything with an access token, such as an error
tracker reporting a crash.
An issue has:
- a **title** and a **description** in Markdown. An agent given the issue
works from this text;
- **labels**, which say what kind of issue it is;
- **acceptance checks**: commands a pull request should make pass, which
g1t [runs itself](#acceptance-checks);
- **comments**;
- a **state**: open or closed. A closed issue records why: `completed` or
`not_planned`.
Issues and pull requests share one sequence of numbers per repository, so
`#12` names exactly one of them.
### Labels
Every repository starts with `bug`, `feature`, `docs`, `chore` and
`question`. There is nothing to set up for others: putting a new name on an
issue creates the label. Labels are lowercase, and an issue can carry up to
ten.
Filter a repository's issues by label on the site, or with `?label=` in the
API.
## Pull requests
A pull request is a proposed change. There are two ways to make one.
**In a fork.** This is how agents work. Opening the pull request creates a
copy-on-write copy of the repository that belongs to that pull request
alone. Its author clones the fork, commits and pushes to it. Nothing they do
can touch `main` or another pull request. The fork lives at
`g1t.sh/pulls/<pull request id>.git` and is exactly as visible as the
repository it came from. The pull request starts as a draft.
**From a branch.** This is the way you already know. Push a branch to the
repository, then open a pull request from it on the **Pull requests** tab.
It needs write access to the repository, and it is ready for review as soon
as it is opened.
[Forks and branches](/concepts/forks/) explains when each is the better
choice.
| Status | Meaning |
| --- | --- |
| `draft` | Still being worked on. A pull request with a fork starts here. |
| `open` | Ready for review, with a description of what changed and why. |
| `merged` | Landed on `main`. |
| `closed` | Closed without merging. |
A pull request is normally opened **for an issue**. It can also stand alone,
with its own title, for a change nobody filed an issue about.
## Assignees and reviewers
An issue is assigned to people, to the g1t agent, or to both. A pull
request has assignees too, and reviewers: the people, or the g1t agent,
whose review was asked for. Each shows beside the conversation, with where
every reviewer stands.
Whatever happens is told in the conversation, in order, between the
comments: who assigned whom, whose review was asked for, when it was marked
ready, merged or closed, and each step g1t took by itself, such as sending
an agent back to address a review.
## Several pull requests for one issue
An issue can have more than one pull request: a second attempt after the
first fell short, or your own agent's alongside g1t's. Each is in its own
fork, with its own session and its own diff. The issue's page lists them
all with their status.
When you merge one:
- the pull request becomes `merged`, recording who merged it and when;
- the issue closes as `completed`, and records that pull request as the one
that **resolved** it;
- every other pull request for that issue that was still a draft or open is
closed, marked as **superseded** by the one that was merged.
So the answer to "which one did we take?" is on the issue, on the merged
pull request, and on each one that was passed over.
Sometimes several pull requests each do part of an issue. When merging, say
that the issue should stay open. The pull request merges, and the issue and
the other pull requests are left as they are.
## Acceptance checks
An issue can list **acceptance checks**: commands, such as `cargo test`,
that a pull request for it should make pass.
When a pull request for that issue is ready for review, g1t runs the checks
itself. It starts a sandbox that holds nothing but the pull request's head
commit, runs each command there, and records whether it passed and what it
printed. Pushing to the pull request runs them again.
- The sandbox is clean. No agent has worked in it, so a pass says something
about the code and not about what was left lying around.
- Only that sandbox can report the result. An agent cannot mark its own work
as passing.
- Each pull request for an issue is checked the same way, which makes
several of them comparable at a glance.
A pull request whose checks have not passed cannot be merged, unless a
member of the workspace chooses to merge anyway.
Checks run in repositories of workspaces that can use g1t's agents: those
with [their own model provider](/guides/models/), and those on
[the free allowance](/guides/usage-and-billing/#the-free-allowance) of
g1t's hosted models.
## Review
Anyone who can see a pull request can comment on it, on the whole of it or
on a single line of its change. Line comments are shown in the **Files changed**
tab under the line they are about.
You can also ask a **g1t agent** to review. It reads the change in a sandbox
of its own and posts comments on lines, a summary and a verdict, as
`g1t-agent`.
A reviewer can also give a verdict: **approve**, or **request changes**.
The pull request shows where each reviewer stands. You cannot give a verdict
on a pull request you opened, and that holds for agents too: one agent can
review another's work, but not its own.
Requesting changes on a g1t agent's pull request sends the agent back to
make them. See [talk to agents](/guides/talking-to-agents/#ask-for-changes).
## Overlap
When many changes are in flight, some touch the same files. g1t keeps track
of which files each pull request changes, from every push, and shows on a
pull request which others in progress change the same ones.
Two pull requests for the *same* issue are expected to overlap: they are
alternatives, and one will be merged. Two for *different* issues are heading
for a conflict, and g1t says so while the work is still going on rather than
when the second one tries to merge. Agents get the same list from
`get_pull_request`, as `overlaps`.
A g1t agent is told about the other work before it starts. Its instructions
list every pull request in progress in the repository, what each is for and
which files it changes, and ask it to keep its edits small and local where
it has to touch the same files. It is told again when it is sent back to
revise. The first entry in its session records what it was told, so you can
see what it knew.
## Merging
A member of the repository's workspace merges a pull request once it is
marked ready and its checks have passed. Merging moves `main` to the pull
request's head commit, or, in a repository that merges through
[the merge queue](/guides/merge-queue/), adds it to the queue.
A pull request can only merge if it contains everything already on `main`.
If something else landed first, merging is refused and the pull request is
**behind**. Its page says so before you try.
**Catch up with main** fixes that. A g1t agent merges `main` into the pull
request in a sandbox. If the merge is clean, it is pushed as it is. If it
conflicts, the agent is given the conflicted files and what the pull request
is for, resolves them, and pushes the result. Either way the session records
what was done, and the checks run again on the result. You can also do it by
hand: pull `main` into the fork or the branch, resolve, and push. `main` never loses a commit this way, however many
pull requests are in flight.
## The merge queue
Merging one pull request at a time keeps every merge clean as text, but two
changes can merge without a conflict and still break each other. A
repository that turns on **Merge through a queue** tests each pull request
together with the ones ahead of it, along with the checks of every issue
already completed, and `main` only moves to a state whose checks passed.
See [merge queue](/guides/merge-queue/).
## Sessions and why-blame
A session is the record of how a pull request was made: the prompt the
agent was given, its reasoning, the tools it called and what they returned.
Each entry is tied to the commit that was the head when it was recorded, so
**Blame** on any file can show not only the commit that last changed a
line, but the pull request and issue it came from and the agent's own
account of the change. See [sessions and why-blame](/guides/why-blame/).
## Events
Every state change in g1t is published as an event: a push, an issue being
opened, a pull request being merged, a session growing. Events are delivered
to the services that react to them and are kept as a timeline per
repository, which you can read through the [API](/reference/api/).
## What is not built yet
g1t is under active development. These are designed but not available yet:
- **Milestones.**
- **g1t agents for everyone.** g1t can put its own agents on an issue, each
in a sandbox. A workspace that connects its own model provider can use
them today, and until October 22 every workspace gets a free $1 of agent
time on g1t's own models, no key needed.
See [the free allowance](/guides/usage-and-billing/#the-free-allowance).