Skip to content
729 linesCodeBlameRaw
1# g1t
2
3> g1t (https://g1t.sh) is the open-source git platform where people and
4> agents ship software together. It is ordinary git over HTTPS, with
5> issues, pull requests and reviews. Agents are members of the forge: you
6> assign an issue to g1t or connect your own over MCP, or hand g1t an
7> outcome and a planner splits it into issues with dependencies that agents
8> work in parallel, aware of each other. A repository's workflows are its
9> checks, for people and agents alike; a merge queue lands each change on main only once it passes together with
10> everything ahead of it, and deployments put a preview of every pull
11> request and production on g1t.page. Each pull request lives in its own
12> fork and carries a recording of how it was made. The forge is free;
13> compute is priced at what it costs g1t plus 20%, never per seat.
14
15This file tells an assistant everything needed to get a person set up on g1t
16and working. You never ask for, see, or send the person's password. Accounts
17are created and approved only in their browser.
18
19## Set someone up
20
211. **Start a sign-in.**
22
23 ```sh
24 curl -X POST https://api.g1t.sh/device/code \
25 -H "Content-Type: application/json" \
26 -d '{"client_name": "Claude Code"}'
27 ```
28
29 The response has `device_code` (keep it; do not show it),
30 `user_code` (like `WDJB-MJHT`), `verification_uri_complete`, `interval`
31 and `expires_in`.
32
332. **Send the person to their browser.** Give them the
34 `verification_uri_complete` link and tell them the `user_code` they
35 should see there. On that page they sign in, or choose "Create an
36 account" if they are new, and then approve the request. Wait for them.
37
38 A new account also gets a confirmation email from `noreply@g1t.sh`. Ask
39 them to open it and follow the link. Until they do, the account cannot
40 create repositories, push, or open issues: those calls return `403`
41 with a message saying to confirm the address.
42
433. **Collect the token.** Poll every `interval` seconds, not faster:
44
45 ```sh
46 curl -X POST https://api.g1t.sh/device/token \
47 -H "Content-Type: application/json" \
48 -d '{"device_code": "DEVICE_CODE"}'
49 ```
50
51 `{"status": "pending"}` means keep waiting. `denied` and `expired` mean
52 start again from step 1. `approved` comes with `token`, `username` and
53 `verified`. The token is returned once. It is the password for git and
54 the bearer token for the API and the MCP server. Store it as `G1T_TOKEN`;
55 never write it into a repository. Your person can see and delete it at
56 g1t.sh/settings/tokens. If `verified` is `false`, the
57 confirmation email has not been followed yet.
58
594. **Connect the MCP server** (any MCP client with HTTP transport works).
60 Claude Code:
61
62 ```sh
63 claude mcp add --transport http g1t https://mcp.g1t.sh \
64 --header "Authorization: Bearer $G1T_TOKEN"
65 ```
66
67 Codex, in `~/.codex/config.toml`:
68
69 ```toml
70 [mcp_servers.g1t]
71 url = "https://mcp.g1t.sh"
72 bearer_token_env_var = "G1T_TOKEN"
73 ```
74
75 OpenCode, in `opencode.json`:
76
77 ```json
78 { "mcp": { "g1t": { "type": "remote", "url": "https://mcp.g1t.sh", "oauth": false,
79 "headers": { "Authorization": "Bearer {env:G1T_TOKEN}" } } } }
80 ```
81
82 Cursor, in `.cursor/mcp.json`:
83
84 ```json
85 { "mcpServers": { "g1t": { "url": "https://mcp.g1t.sh",
86 "headers": { "Authorization": "Bearer ${env:G1T_TOKEN}" } } } }
87 ```
88
89 Without the header, a client that supports MCP authorization signs the
90 person in through their browser instead (Claude Code: `/mcp`, then
91 choose g1t; Codex: `codex mcp login g1t`; OpenCode: `opencode mcp auth
92 g1t`; Cursor: when it first connects). The MCP server always needs one
93 or the other.
94
955. **Create a workspace** if `GET /user` shows none. A workspace owns
96 repositories and is the first part of their address. Ask the person what
97 to call it; their username is a sensible default.
98
99 ```sh
100 curl -X POST https://api.g1t.sh/workspaces \
101 -H "Authorization: Bearer $G1T_TOKEN" -H "Content-Type: application/json" \
102 -d '{"slug": "WORKSPACE"}'
103 ```
104
1056. **Or import one.** `POST /repos` with `name` and
106 `import_url` (the https address of a public repository, such as one on
107 GitHub) copies its default branch.
108
1097. **Push a repository.** Pushing to a repository that does not exist, in a
110 workspace the person belongs to, creates it, public by default.
111
112 ```sh
113 git remote add g1t https://g1t.sh/WORKSPACE/REPO.git
114 git -c credential.helper= \
115 -c "http.extraHeader=Authorization: Basic $(printf '%s' "USERNAME:$G1T_TOKEN" | base64)" \
116 push -u g1t main
117 ```
118
119 Or let git ask: the username is the g1t username and the password is the
120 token.
121
1228. **Record Claude Code sessions automatically** (optional). This installs
123 hooks that record prompts, tool calls and replies onto the g1t pull
124 request for the branch being worked on. The person runs it, because it
125 signs them in through their browser:
126
127 ```sh
128 curl -fsSL https://g1t.sh/install/claude.sh | sh
129 ```
130
131## Do work
132
133Issues and pull requests are addressed by repository and number, and share
134one sequence of numbers: `#12` is one or the other. Below, `{repo}` stands
135for `/repos/{owner}/{name}`.
136
137- **Find work:** `GET {repo}/issues?state=open`, optionally `&label=bug`
138 or `&milestone=3`.
139- **Open an issue:** `POST {repo}/issues` with `title`, `body`, and
140 optional `labels` (the repository's, from `GET {repo}/labels`, such as
141 `bug` or `enhancement`; a new name makes a new label only for someone
142 with the Triage role) and `milestone` (a number from
143 `GET {repo}/milestones`). Say what done means in the body, under `## Definition of done`
144 if you like; it guides whoever does the work but never gates a merge.
145 The old `checks` field is deprecated: its commands are added to the body
146 under "Definition of done" and the response has a `deprecation` note.
147- **Read an issue:** `GET {repo}/issues/{number}`. It lists every pull
148 request already made for it. A closed issue's `resolved_by` is the number
149 of the pull request that was merged.
150- **Open a pull request:** `POST {repo}/pulls` with `issue` (its number) and
151 `agent` (a label such as `claude-code`). Without an issue, send `title`.
152 The response has `pull.number` and `git.remote`, the pull request's own
153 fork. Clone it, commit, and push to it with the token. It starts as a
154 draft. It merges into the default branch; send `base` only when asked
155 to target another branch. If the change is already on a branch pushed to the repository,
156 send `branch` (and `title`, `body`) instead: no fork is made and the pull
157 request is ready at once.
158- **Record the session** as you work, so people can see why a change was
159 made: `POST {repo}/pulls/{number}/session` with
160 `{"entries": [{"kind": "message", "text": "…"}]}`. Kinds are `prompt`,
161 `message`, `tool_call`, `tool_result`, `note`. Never include secrets;
162 sessions are as visible as the repository.
163- **Mark it ready:** `POST {repo}/pulls/{number}/ready` with `summary`, which
164 becomes the pull request's description.
165- **See what a pull request changes:** `GET {repo}/pulls/{number}/changes`.
166- **Before going far**, read `overlaps` on `GET {repo}/pulls/{number}`:
167 other pull requests in progress changing the same files. `behind` says
168 whether main has moved since; if so, pull main into the fork and push.
169- **Checks:** the repository's workflows (`.g1t/workflows`, GitHub Actions
170 syntax) run on every pull request's head, and each reports a check named
171 after the workflow, such as `CI`. Before you push, run the same tests and
172 linters those workflows run. `GET {repo}/pulls/{number}` returns
173 `statuses`, `required_checks` and `rules`: each check the branch it merges into
174 requires, as `success`, `failure`, `pending` or `expected` (not reported
175 yet). If one failed, read why with `GET {repo}/actions/runs/{id}` and
176 `GET {repo}/actions/jobs/{job}/logs`, push a fix, and the workflows run
177 again. `GET {repo}/commits/{ref}/check-runs` lists every check run on a
178 commit (each workflow job is one), and
179 `GET {repo}/check-runs/{id}/annotations` the lines a failing one points at.
180 `GET {repo}/check-names` lists the check names seen in the last
181 30 days. `rules.unmet` lists every rule of that branch not met yet, with
182 what to do; `GET {repo}/rules/branches/{branch}` lists every rule. Rules
183 hold for agents exactly as for people: a push that breaks one is refused
184 with the ruleset and rule named, so read the `remote:` lines and fix the
185 commits. `required_checks` on `PATCH {repo}/settings` sets which ones a
186 merge needs.
187- **Comment** on an issue or a pull request:
188 `POST {repo}/issues/{number}/comments` with `body`. On a pull request, add
189 `path` and `line` to comment on one line of the change.
190- **Review** someone else's pull request:
191 `POST {repo}/pulls/{number}/reviews` with `verdict` (`approve` or
192 `request_changes`) and `body`.
193- **Merge** (the Write role or higher on the repository):
194 `POST {repo}/pulls/{number}/merge`. This closes the issue it was for and
195 closes the other pull requests for that issue as superseded; send
196 `{"keep_issue_open": true}` if this is only part of the work. If main has
197 moved, g1t brings the pull request up to date and lands it when that is
198 done. A repository that requires pull requests to be up to date answers
199 `409` instead: pull main from `https://g1t.sh/{owner}/{name}.git` into the
200 fork, push, and merge again.
201 With the merge queue on, merging adds the pull request to the queue
202 instead; `GET {repo}/queue` shows it being tested with the pull requests
203 ahead of it, and it lands only if that combination passes.
204
205## Hand work to g1t
206
207Agents, workflows and the merge queue run on g1t's machines, so they
208need a paid workspace, or the one-time $5 trial after a card check.
209Deployments need the plan; the trial never covers them. Workflows and the merge queue on public repositories
210can also run from g1t's open-source pool, after the same card check.
211Agents never run from the pool. Workflow jobs with `runs-on: self-hosted`
212run on the workspace's own machines (`g1t-runner`, any OS) at $0, on every
213plan; a workspace can send agent work there too. Each workspace decides how its agents
214reach a model: its own provider (connected under Integrations, billed by
215the provider) or g1t's hosted models (while payments are in test mode,
216only for a few invited workspaces; a trial does not open them, and an
217agent assigned without a model is refused with `no_model`); the sandbox is g1t's unless the work goes to
218the workspace's own runners.
219When the plan refuses a start, these calls answer with a failure whose
220message says what to do and where (such as `/acme/-/billing`). When every
221agent slot of the workspace is busy, the message starts "Waiting for a
222free slot" and the work starts by itself when one finishes.
223
224- **Hand off an outcome:** `POST {repo}/plans` with `brief`: what should be
225 true when the work is done. A planner reads the repository and proposes
226 issues, each with what done means (`done`), the files it touches, and what it depends
227 on. Read it with `GET {repo}/plans/{plan}` until `status` is `ready`
228 (a minute or two), then `POST {repo}/plans/{plan}/apply` with
229 `{"assign": true}`. Agents start at once on every issue that depends on
230 nothing and on the rest as what they depend on lands. `keep` opens only
231 some of the issues, by position counting from 1.
232- **Assign one issue:** `POST {repo}/issues/{number}/assign`. The agent
233 opens a pull request, waits for the repository's workflows on it and is
234 sent back with the failing jobs' log tails when one fails, is reviewed by
235 a second agent, revises, and catches up when main moves. After its
236 revisions (`max_revisions`, 2 by default) only a required check still
237 failing holds it for a person. There is no model or
238 agent count to choose: to put more agents to work, assign more issues.
239 On g1t's hosted models, Auto routes each job to the cheapest of three
240 tiers that can do it, fast, standard and most capable: catching up,
241 answering and reviews of small changes that touch no sensitive path
242 start fast; making changes, revising, planning and other reviews start
243 standard; reviews of very large changes and issues labelled
244 `architecture` start most capable. A failed attempt moves the next one
245 up a tier (two in a row: most capable), and a repository's own recent
246 runs move work down or up. Each run states its model and why in one
247 line, on the run and in the session. An owner can pin a tier per kind of
248 work instead (`PUT /workspaces/{workspace}/model-routes`, `model`
249 `small`, `large` or `frontier` with `connection_id` null).
250- **Who a g1t pull request is for:** g1t is the `author` (`username`
251 `g1t`, `kind` `agent`) of every pull request it makes and every issue it
252 files at work; `requested_by` is the person who asked (null when nobody
253 did, as for a security update). That person answers for it as an author
254 would: they may update, close and steer it without Triage, cannot
255 approve it, are never asked to review it, see it in their own lists, and
256 its sandboxes, workflows and previews are trusted as they are. Webhooks
257 carry `data.author` and `data.requested_by`; Actions payloads
258 `pull_request.user` (a `Bot`) and `pull_request.requested_by`.
259- **Put an agent on something in one step:** `POST {repo}/issues/delegate`
260 with `title` and `body` (what to do, in plain words, and what done
261 means if you know it). It opens the issue and assigns g1t at once; it needs the
262 Write role, and nothing opens without it. The issue opens even when the
263 agent cannot start: `agent.status` is `started` (with `pull`), `queued`,
264 or `not_started` with `agent.code` (`not_paid`, `trial_used`, `limit`,
265 `paused`, `issue_cap`, `billing_unavailable`, `no_model`), `agent.message`
266 and `agent.fix_url`.
267- **How sure g1t is of a change:** once g1t finishes, the pull
268 request's `confidence` is `high`, `medium` or `low` with short `reasons`
269 ("tests not added", "3 revisions"), from its required checks, revisions, review,
270 tests, size, reach, guardrails and unanswered questions. The agent's own
271 word (`self_reported`, `uncertain_about`) can only lower it. With the
272 repository setting `hold_low_confidence` on (the default), a change rated
273 low waits for a person's approval instead of merging by itself.
274- **Steer a working agent:** `POST {repo}/pulls/{number}/messages` with
275 `body`. It reads the message at its next step.
276- **g1t's runs talk to each other.** g1t asks the agent on another
277 pull request a question, or hands it work, with `agent` `message`
278 (`kind` `question` or `handoff`, and `from_number`, its own pull
279 request). The other agent replies with `agent` `answer`
280 (`POST {repo}/messages/{id}/answer`); one that is not at work is woken
281 to answer, in its own pull request's sandbox. Plans show these exchanges under
282 "Agents talking". From any other caller, `agent` `message` sends a plain
283 message.
284
285Every one of these is also on the MCP server. Its tools are resources,
286each with an `action`: `search`, `repository`, `issue`, `pull_request`,
287`agent`, `plan`, `memory`, `workflow`, `secret`, `webhook`, `access`,
288`workspace`, `notifications` and `account`. Call `tools/call` with the tool's name and
289`arguments` holding `action` and its inputs, such as
290`{"name": "issue", "arguments": {"action": "get", "repo": "acme/web", "number": 12}}`.
291The flow above is: `issue` `get`, `memory` `recall`, `pull_request`
292`create` (with `issue`), push, `pull_request` `record_session` as you go,
293`pull_request` `ready` with `summary`; read `overlaps`, `behind`,
294`statuses` and `required_checks` on `pull_request` `get`, and
295`repository` `check_names` for the names a branch can require;
296`workflow` `list_check_runs` and `check_run_annotations` for what a
297commit's checks say. `agent` `delegate` and `agent` `assign` hand work
298to g1t's agent; `plan` `create`, `get` and `apply` plan an outcome;
299`memory` `remember` saves a fact. `notifications` reads and answers the
300inbox of the person a token acts for: `list` (unread threads, each with a
301`reason` such as `agent` or `review_requested`), `done`, `subscribe`,
302`watch` and more; g1t's own token cannot use it. `search` runs `code`,
303`notifications` runs `list` and `account` runs `whoami` when `action` is
304left out. A call missing a required field says
305which, such as "issue.get needs number.". The earlier one-tool-per-operation
306names (`get_issue`, `create_pull_request`, …) still answer for now but are
307no longer listed. Every tool and action, with its required fields and
308scope: https://docs.g1t.sh/reference/mcp/
309
310g1t's own token can never change a repository's details, rename it
311or its branches, make it public or private, archive, transfer, delete,
312restore or purge it, or delete a workspace. MCP tools take the repository
313as `repo`, written `owner/name`.
314
315## Scopes
316
317Every access token and OAuth sign-in has scopes, `resource:level`:
318`repo`, `code`, `issues`, `pull_requests`, `workflows`, `checks`, `deployments`, `memory`,
319`account`, `notifications`, `access`, `webhooks`, `secrets`, `runners`, `models` (read, write or admin
320as each has them), `agents:run`, `workspace:read` and `workspace:admin`. A higher
321level includes the lower. A token may expire. It reaches every workspace
322and repository its owner can (a workspace's token, that workspace only);
323what a call may do is the owner's role and the token's scopes together.
324A token sees only the MCP tools and actions its scopes allow. A missing scope answers `403` with
325`{"error": {"code": "forbidden", "message": "This access token needs the issues:write scope to use create_issue.", "needed_scope": "issues:write"}}`.
326Pushing needs `code:write`; cloning a private repository `code:read`. For
327an agent, use the Agent preset (every read scope but `runners:read`, plus `code:write`,
328`issues:write`, `pull_requests:write`, `agents:run`, `memory:write`,
329`notifications:write`). For CI, the CI preset (`repo:read`, `code:read`,
330`code:write`, `packages:read`, `packages:write`, `workflows:read`,
331`workflows:write`, `deployments:read`, `deployments:write`). `models:write` (sending requests through the AI
332Gateway, which spends AI credit) is in no preset but full access.
333OAuth clients may send `scope`;
334the person can untick any; asking for none gives the Agent preset. Tokens
335from device sign-in (above) have full access. Guide:
336https://docs.g1t.sh/guides/authentication/#scopes
337
338## AI Gateway
339
340Your own code can call models through g1t: base URL
341`https://models.g1t.sh/anthropic`, API key a workspace access token with
342`models:write` (as `x-api-key` or `Authorization: Bearer`). It serves
343Anthropic's Messages API as it is: `POST /v1/messages` (streamed or not)
344and `POST /v1/messages/count_tokens`. Models: `claude-opus-5-5`,
345`claude-sonnet-5-5`, `claude-haiku-4-5`. Each request is charged at the
346model's list price (no markup in beta) from included usage and AI credit,
347never the agent rate; on the workspace's own Anthropic key under
348Integrations it is free and only counted. Refusals are Anthropic-shaped:
349`402 billing_error` when out of AI credit, over the spend limit or not on
350the plan; `403 permission_error` without `models:write` or with a personal
351token; `400 invalid_request_error` for a model not offered, or on g1t's
352models for fast mode (`speed`), `inference_geo`, `fallbacks`, `container`
353or server tools such as web search (all fine on the workspace's own key). For Claude
354Code: `ANTHROPIC_BASE_URL=https://models.g1t.sh/anthropic` and
355`ANTHROPIC_AUTH_TOKEN=g1t_…`. The log (30 days, no prompts):
356`GET /workspaces/{workspace}/gateway/requests` or the `billing` tool's
357`gateway_requests` action, with `models:read`. OpenAI's format and open
358models come later. Guide: https://docs.g1t.sh/guides/ai-gateway/
359
360## Access and roles
361
362Everyone's access to a repository is a role: `read` (read, clone, open
363issues and pull requests, comment), `triage` (also label, assign, close),
364`write` (also push, merge, and put agents to work: anything that spends
365compute), `maintain` (also settings, branch protection, guardrails) or
366`admin` (also webhooks, secrets, deployments, domains, who has access,
367rename, archive, visibility, default branch). Owners of a workspace have
368admin on all of its repositories and alone transfer or delete them;
369members get the workspace's base permission (write unless owners change
370it); anyone can be given a role on one repository, as an outside
371collaborator; anyone reads a public repository. The highest wins. A
372private repository you cannot read answers `404`; one you can read but
373lack the role for answers `403` naming the role needed. An agent works
374with the role of the person it acts for on its repository, never more
375than `write`, and its token can never change who has access. An outside
376collaborator with `write` can put agents to work; the runs are charged to
377the repository's workspace, and their agents are told the project's memory,
378never the workspace's. Who can do what elsewhere: deployments are seen with
379`read` (on a public repository, by anyone, build logs included), deployed
380with `write`, configured (settings, domains) with `admin`; project settings
381and dependencies need `maintain`; repository webhooks, secrets and
382variables need `admin`, seeing them included; security alerts need
383`write` (dismissing a dependency alert too), dismissing or reopening a
384secret alert `admin`, turning security updates on or off `maintain`;
385enabling or disabling a workflow needs `maintain`; plans and project memory
386are read by anyone who can read the repository, and project memory is
387changed with `write`; workspace memory is for members. People: the
388workspace's Settings → Members (`g1t.sh/<owner>/-/people`, with an Outside
389collaborators tab and the Base permission for owners); a repository's
390Settings → Access (`g1t.sh/<owner>/<repo>/settings/access`); invitations
391are answered at `g1t.sh/<owner>/<repo>/invitations`.
392`GET {repo}/collaborators/{username}/permission` gives a role and what it
393allows. Guide: https://docs.g1t.sh/guides/access-and-roles/
394
395Teams group a workspace's members (`GET /workspaces/{workspace}/teams`;
396the `team` MCP tool). A team given a role on a repository gives it to
397everyone in it and its child teams, and `source` is then `team`.
398`@workspace/team` in a comment tells the team's people; a pull request can
399ask a team to review (`POST {repo}/pulls/{number}/requested_reviewers` with
400`team_reviewers`), and the team may pick who. Guide:
401https://docs.g1t.sh/guides/teams/
402
403A CODEOWNERS file (`.g1t/CODEOWNERS`, `.github/CODEOWNERS`, `CODEOWNERS`,
404`docs/CODEOWNERS` or `.gitlab/CODEOWNERS`, the first found on the default
405branch) asks owners to review pull requests that change their files. With
406`require_code_owner_review` on (`PATCH {repo}/settings`), a merge waits for
407their approval; `code_owners` on `GET {repo}/pulls/{number}` says whose is
408missing, and `GET {repo}/codeowners/errors` checks the file. Guide:
409https://docs.g1t.sh/guides/codeowners/
410
411## Manage a repository
412
413People with the admin role rename it (`POST {repo}/rename` with `name`; the
414old address redirects), make it public or private
415(`POST {repo}/visibility` with `private` and its full name in `confirm`),
416archive or unarchive it (`POST {repo}/archive`, `POST {repo}/unarchive`),
417and owners of its workspace delete it (`DELETE {repo}` with its full name
418in `confirm`). A deleted
419repository can be restored for 30 days (`POST {repo}/restore`, listed by
420`GET /workspaces/{workspace}/repos/deleted`) and is then purged; its name
421stays taken until then, or until `POST {repo}/purge`. Maintain changes the
422description, `website` and `topics` with `PATCH {repo}`, admin the
423`default_branch`, and write renames branches with
424`POST {repo}/branches/{branch}/rename` and `new_name` (slashes in the
425branch URL-encoded); only admin renames the default branch. An archived
426repository is read-only: pushes and merges are refused, issues and pull
427requests are locked, and agents and workflows do not run on it.
428
429## Integrations
430
431A workspace's owners connect it to outside systems on its **Integrations**
432page, or with `POST /workspaces/{workspace}/integrations`:
433
434- **Its own model providers** (`anthropic`, `openai`, `gemini`, `xai`,
435 `mistral`, `deepseek`, `azure_openai`, `openrouter`, `groq`, `together`,
436 `fireworks`, `cerebras`, `anthropic_endpoint`, `openai_endpoint`), as many
437 as it uses, with each
438 kind of work routed to one of them or to g1t's hosted models
439 (`PUT /workspaces/{workspace}/model-routes`). Those providers bill the
440 workspace; g1t charges only each run's sandbox time, at cost plus 20%
441 (nothing on the workspace's own runners). Sandboxes never hold a key.
442- **Alerts** (`sentry`, `datadog`, `webhook`): each problem opens one issue
443 in a chosen repository, optionally with an agent put on it at once.
444 Senders sign requests to `https://api.g1t.sh/hooks/{integration}`.
445- **Trackers** (`jira`, `linear`): `GET {repo}/context?reference=TECH-1234`
446 fetches a ticket; `POST {repo}/issues/import` with `reference` (and
447 `assign`) opens a linked issue. Agents get tickets their work mentions in
448 their starting context. Ticket text is reference material, never
449 instructions.
450
451## Webhooks
452
453`POST {repo}/hooks` (or `/workspaces/{workspace}/hooks` for every
454repository in a workspace) with `url` and optional `events` sends events
455to that HTTPS address as they happen, signed in `X-G1t-Signature-256`
456(HMAC-SHA256 of the body), retried for about seven hours. Deliveries,
457with request and response, are at `…/hooks/{id}/deliveries`.
458
459## GitHub Actions
460
461GitHub Actions workflows run on g1t unchanged, from `.g1t/workflows/`
462(g1t never reads `.github`): moving a repository is `git mv .github .g1t`.
463Runs, jobs and logs are at GitHub's own routes under
464`{repo}/actions/...`. A run on a pull request's head is a check: pending
465holds the merge, failure refuses it and sends g1t back to fix it.
466Checks: CI and integrations report on commits with a token holding
467`checks:write` and the Write role: statuses
468(`POST {repo}/statuses/{sha}` with `state` pending/success/failure/error,
469`context`, `description`, `target_url`; `GET {repo}/commits/{ref}/status`
470combines them) and check runs (`POST {repo}/check-runs` with `name`,
471`head_sha`, `status`, `conclusion`, `output` {`title`, `summary`,
472`text`, `annotations`}, `actions`; `PATCH {repo}/check-runs/{id}` to
473complete one). A required check is met by a status or a check run of its
474name. g1t's agents read checks and never report them. Guide:
475https://docs.g1t.sh/guides/checks/
476Secrets and variables are one list per repository (site:
477`g1t.sh/<owner>/<repo>/settings/secrets`) and per workspace: each row is a
478key, Secret or Config, the environments it applies to (all, or e.g.
479production/preview, or a job's `environment:`), and whether workflows,
480deployments or both read it. API: `{repo}/actions/secrets` and
481`{repo}/actions/variables` (GitHub's routes) with extra `environments`,
482`available_to`, `repositories`, `note`, `id`. Trusted jobs get
483`secrets.G1T_TOKEN` (the workspace's token; `GITHUB_TOKEN` is its alias),
484which cannot change secrets. A pull request's runs and preview are trusted
485only when its author has `write` or higher on the repository (a member or
486an outside collaborator), or is g1t working on its own; for one g1t made,
487the role of whoever asked for it (`requested_by`) counts. Anyone else's run
488with config only. Guide:
489https://docs.g1t.sh/guides/secrets-and-variables/
490
491Self-hosted runners: a job with `runs-on: self-hosted` (or
492`[self-hosted, linux, gpu]`, or `{group: name}`) waits until a runner of the
493workspace's with every label takes it. Owners add one under
494`g1t.sh/<workspace>/-/runners`: a one-hour registration token, then
495`g1t-runner register --url https://g1t.sh --token g1trt_…` and
496`g1t-runner run`. Runners only connect out. API:
497`/workspaces/{workspace}/actions/runners`, `.../runner-groups`,
498`.../runner-settings` (and the same under `{repo}/actions/` for a
499repository's own); MCP: the `workflow` tool's `list_runners`,
500`create_runner_token`, `remove_runner`, runner group and settings actions
501(`runners:read`/`runners:admin`). Pull requests from forks never run on them
502unless allowed. Guide: https://docs.g1t.sh/guides/self-hosted-runners/
503
504## Projects
505
506A project is what a workspace builds and runs; every repository is a
507project of its own name (`g1t.sh/<owner>/<project>` opens its overview; its
508code is under `/code`; every repository address still works). Deployments,
509secrets and variables belong to the project; branches, pull requests,
510review and merge rules to its repository (Settings → Repository). Guide:
511https://docs.g1t.sh/guides/projects/
512
513## Security
514
515A push that adds a known key or token format (AWS, GitHub, GitLab, Stripe
516live, Slack tokens and webhooks, Google, Anthropic, OpenAI, npm, g1t,
517SendGrid, PEM private keys, service-role JWTs) is refused with every secret
518listed by `file:line` in git's output and a link to allow it; this includes
519an agent's push to its pull request. A very large push is scanned after it
520lands, not before: it goes through, its new commits (any branch) are
521scanned in the background, and a secret found is an open alert, emailed to
522the workspace's owners when it looks real. History is scanned once in the
523background. Never commit a secret: read it from the environment. Values are
524judged by the value alone, never the file's path: a documented example key,
525a value containing example/sample/dummy/fake/placeholder/changeme/notreal/
526redacted/xxxxx, one that counts up (six or more, like 123456), one
527character five or more times, a repeated short piece, or too little
528randomness is a "likely test value": listed apart, never blocks a push,
529never counted critical. Any other fixture carries `g1t:allow-secret` in a
530comment on its line. Alerts are `open`, `dismissed` or `fixed`. Dismissing a
531secret alert needs `admin`, with a reason (`false_positive`,
532`used_in_tests`, `wont_fix`: dismissed, and pushes carrying it go through;
533`revoked`: fixed) and an optional comment (500 characters); a dependency
534alert needs `write` (`fix_started`, `no_bandwidth`, `tolerable_risk`,
535`inaccurate`, `not_used`). Reopen undoes it. API:
536`GET {repo}/security/alerts` (`state`, `kind`),
537`POST {repo}/security/alerts/{id}/dismiss` (`reason`, `comment`),
538`POST {repo}/security/alerts/{id}/reopen`; MCP `repository` actions
539`security_alerts`, `dismiss_alert`, `reopen_alert` (`repo:read` to list,
540`repo:admin` to dismiss or reopen). Lockfiles (npm, pnpm, yarn, Cargo, Go,
541Python) on the default branch are checked against OSV on every push to it
542and daily. Security updates (on by default; `maintain` turns them off): for
543each vulnerable dependency with a fix, g1t itself opens a pull request
544authored by `g1t` from `g1t/security/<package>-<version>`, raising the
545version in each lockfile with the ecosystem's own tool; it merges through
546the branch's required checks and merge queue. A newer update for the same
547package, or the package no longer being vulnerable, closes it as
548superseded. Only when the bump fails, or required checks fail because code
549must change, does g1t open an issue and assign it to g1t (the session
550shows "started by g1t"). With no fix published, the alert links the
551advisory and is checked again daily. `.g1t/dependencies.yml` (version
552updates) is read and validated, but no version update pull requests are
553opened yet. `g1t` is not an account and cannot be signed in to.
554Guide: https://docs.g1t.sh/guides/security/
555
556The security suite (scopes `security:read`, `security:write`; MCP tool
557`security`). A push refused for a secret links to its alert, where anyone
558with `write` bypasses it with a reason (`false_positive`, `used_in_tests`,
559`will_fix_later`), or asks owners when the workspace delegates bypasses;
560an agent never bypasses: take the secret out and push again. Code
561scanning: upload SARIF 2.1.0 to `POST {repo}/code-scanning/sarifs`
562(`commit_sha`, `ref`, `sarif` gzipped then base64); default-branch results
563become alerts, pull request results (`refs/pull/<n>/head`) become line
564comments and the `Code scanning` status. `Dependency review` is a status on
565every pull request that changes a lockfile. Fix what either reports in your
566own pull request; both can be required checks. Also: custom patterns,
567validity checks, `GET {repo}/dependency-graph/sbom` (SPDX 2.3, in `sbom`),
568`GET {repo}/dependency-graph/compare/{base...head}`, and a workspace
569overview. On private repositories these need the Security and quality
570activation (`402` without it); public repositories have them free.
571Guides: https://docs.g1t.sh/guides/security/secret-protection/,
572https://docs.g1t.sh/guides/security/code-scanning/,
573https://docs.g1t.sh/guides/security/supply-chain/
574
575## Deployments
576
577Part of the g1t plan ($20 a month per workspace, started by an owner
578under the workspace's Billing). No quotas: unlimited projects and
579previews (never charged); builds by the second, requests ($0.36/M), CPU
580($0.024/M ms) and custom domains ($0.12 a month each) metered from the
581first at cost + 20%, from the plan's $10 first. The trial
582never covers deployments. Then someone with admin on the repository
583turns deployments on for a project (Settings → Deployments, or Deploy on
584its overview). Production deploys from the default branch to
585`https://<project>-<owner>.g1t.page` on each push; every branch with an
586open pull request gets a preview at
587`https://<project>-git-<branch>-<owner>.g1t.page` (a fork's pull request is
588`pr-<n>`), shown on it as the check `g1t / deploy` (`g1t / deploy (<project>)`
589for a workspace's other projects). Builds and running apps
590read the project's secrets and variables available to Deployments, each
591key's Production or Preview row. Workers projects (`wrangler.jsonc`) and
592static sites build without configuration. Previews come down when the pull
593request closes and after idle days.
594Guide: https://docs.g1t.sh/guides/deployments/
595
596A repository's deployments, wherever they run, are one list: `source` is
597`api` (reported from any CI), `actions` (a g1t Actions job with
598`environment:`) or `g1t_page` (g1t.page builds, ids `dpl_…`, environments
599`production` and `preview`). Read with `GET {repo}/deployments` (filters
600`environment`, `ref`, `sha`, `task`, `state`, `source`, `creator`, `page`,
601`per_page`), `GET {repo}/deployments/{id}`, `GET {repo}/deployments/{id}/statuses`,
602`GET {repo}/environments` and `GET {repo}/environments/{environment}`
603(`deployments:read`, Read role). Report from a CI with
604`POST {repo}/deployments` (`ref`, optional `environment` (default
605`production`), `sha`, `task`, `description`, `payload`, `state`,
606`environment_url`, `log_url`), then
607`POST {repo}/deployments/{id}/statuses` with `state` (`queued`,
608`in_progress`, `success`, `failure`, `error`, `inactive`) and
609`environment_url` (`deployments:write`, Write role). A success makes the
610environment's older successful deployments `inactive` unless
611`auto_inactive: false`. Each status sets the commit check
612`deploy / <environment>`, which a ruleset's `required_deployments` rule can
613require. A g1t Actions job with `environment:` (or `{name, url}`) reports
614by itself, one deployment per run and environment; `deployment: false`
615opts out. MCP: the `workflow` tool's `list_deployments`, `get_deployment`,
616`create_deployment`, `deployment_statuses`, `create_deployment_status`,
617`list_environments`, `get_environment`. Webhooks: `deployment.created`,
618`deployment_status.created`. Guide: https://docs.g1t.sh/guides/deployments-api/
619
620## Search
621
622`GET https://api.g1t.sh/search?q=<query>&type=<type>` (MCP: `search`, action `code`, the default)
623searches all of g1t: repositories (name, description, topics, README), code
624on default branches, issues, pull requests, people and workspaces. No token
625needed for public results; with one, private results the token's person
626can read are included (their workspaces' repositories, and those they were
627given a role on), checked against current membership and roles. `type` is
628`repositories`, `code`, `issues`, `pulls` or `people` (worked out from the
629qualifiers when left out); `page` and `per_page` (at most 50) page through.
630The query takes words, `"exact phrases"`, `-word` to leave out, and
631`repo:owner/name`, `org:<workspace>`, `language:<lang>`, `path:<prefix or
632*.glob>`, `is:issue`, `is:pr`, `is:open`, `is:closed`, `is:merged`,
633`author:<username>`, `label:<label>`. Code search matches any run of three
634characters or more; vendored directories, lockfiles, binaries and files
635over 512 KB are not indexed. Results give `counts` per type and each hit's
636`snippet` or code `lines` as parts with `highlight`. On the site:
637`https://g1t.sh/search?q=`, ⌘K, and `https://g1t.sh/explore` for public
638projects by activity, language (`?language=`) and topic (`?topic=`).
639The `search` tool's `context` action stays the search of one workspace's
640context hub. Guide:
641https://docs.g1t.sh/guides/search/
642
643## Facts
644
645- API base: `https://api.g1t.sh`. `GET /` lists the main URLs as templates;
646 every operation is in the OpenAPI document.
647 Auth: `Authorization: Bearer g1t_…`. Public data needs no token. Errors are
648 `{"error": {"code": "…", "message": "…"}}` with codes `unauthenticated`
649 (401), `payment_required` (402, when the plan or a limit refuses compute),
650 `forbidden` (403, with `needed_scope` when the token lacks a
651 scope), `not_found` (404), `conflict` (409), `invalid` (422). Each
652 operation's scope is `x-scope` in the OpenAPI document. The full description is at https://api.g1t.sh/openapi.json.
653- Git remote: `https://g1t.sh/{workspace}/{repo}.git`. In API paths,
654 `{owner}` is the workspace. Pull request forks:
655 `https://g1t.sh/pulls/{pull_request_id}.git`. SSH is not available.
656- Limits: 1 GB per repository, 32 MB per file, 100 MB per push. Every
657 current limit, why it exists and the workaround:
658 https://docs.g1t.sh/about/limitations/
659- Forgotten password: https://g1t.sh/forgot (the person does this, in a
660 browser).
661- Times are RFC 3339 in UTC.
662- OAuth 2.1 for applications: metadata at
663 `https://api.g1t.sh/.well-known/oauth-authorization-server`; authorization
664 code with PKCE (S256), public clients, dynamic registration.
665- A pull request whose required checks have not passed (failed, still
666 running, or not reported yet) is refused a merge with `409`, saying
667 which; where the repository allows bypassing them
668 (`allow_ignoring_checks`), someone who can merge can send
669 `{"ignore_checks": true}`. Checks that are not required never hold a
670 merge. With the merge queue on, the workflows behind required checks
671 need `merge_group` in their `on:`.
672- Landing fast-forwards the default branch: g1t makes no merge commit on
673 main. Bringing a pull request up to date makes a merge commit on its own
674 branch.
675- Pricing (https://g1t.sh/pricing): the forge is free. One plan, g1t, at
676 $20 a month per workspace with unlimited members, includes $10 of usage
677 at cost + 20% (unused does not roll over). Compute needs the plan or a
678 card check (never charged); the $5 trial needs a credit or debit card,
679 not a prepaid one. No quotas on the plan: everything is metered from the
680 first unit at cost + 20%, and only the spend limit stops work. Every
681 workspace has 1 GB of private storage and 50,000 git operations a month
682 free; past them, the plan pays ($0.60/GB-month, $0.18/1,000) and a free
683 workspace is held (pushes to private repositories stop; git slowed to 60
684 an hour). Limits: $100 in a
685 paid workspace's first month, rising as payments clear; owners set a
686 spend limit, prepay, or ask with Raise my limit. Caps: $2 a run and $10
687 an issue by default. A spend spike pauses new compute until an owner
688 chooses Keep going or Stop (`/<workspace>/-/billing`). Audit log: 90 days
689 on every plan.
690
691## More
692
693- [Quickstart](https://docs.g1t.sh/quickstart/)
694- [How g1t works](https://docs.g1t.sh/concepts/overview/)
695- [Search and Explore](https://docs.g1t.sh/guides/search/)
696- [g1t's agent](https://docs.g1t.sh/guides/working-with-g1t/)
697- [Outcomes and plans](https://docs.g1t.sh/guides/outcomes/)
698- [Talking to agents](https://docs.g1t.sh/guides/talking-to-agents/)
699- [Bring your own agent](https://docs.g1t.sh/guides/bring-your-own-agent/)
700- [The merge queue](https://docs.g1t.sh/guides/merge-queue/)
701- [Sessions and why-blame](https://docs.g1t.sh/guides/why-blame/)
702- [Forks and branches](https://docs.g1t.sh/concepts/forks/)
703- [Accounts and sign-in](https://docs.g1t.sh/guides/authentication/)
704- [Workspaces and tokens](https://docs.g1t.sh/guides/workspaces/)
705- [Access and roles](https://docs.g1t.sh/guides/access-and-roles/)
706- [Teams](https://docs.g1t.sh/guides/teams/)
707- [CODEOWNERS](https://docs.g1t.sh/guides/codeowners/)
708- [Managing a repository](https://docs.g1t.sh/guides/managing-repositories/)
709- [Integrations](https://docs.g1t.sh/guides/integrations/)
710- [Model providers](https://docs.g1t.sh/guides/models/)
711- [AI Gateway](https://docs.g1t.sh/guides/ai-gateway/)
712- [Webhooks](https://docs.g1t.sh/guides/webhooks/)
713- [GitHub Actions](https://docs.g1t.sh/guides/actions/)
714- [Self-hosted runners](https://docs.g1t.sh/guides/self-hosted-runners/)
715- [Usage and billing](https://docs.g1t.sh/guides/usage-and-billing/)
716- [Git](https://docs.g1t.sh/guides/git/)
717- [MCP tools](https://docs.g1t.sh/reference/mcp/)
718- [API reference](https://docs.g1t.sh/reference/api/)
719- [What g1t can't do yet](https://docs.g1t.sh/about/limitations/)
720- [An open letter to Cloudflare](https://docs.g1t.sh/about/open-letter-to-cloudflare/)
721- [Source](https://g1t.sh/flagon-io/g1t), MIT licensed
722
723## Help, status and policies
724
725- [Status](https://status.g1t.sh/): whether each part of g1t is working now, 90 days of uptime, and incidents; the same as JSON at https://status.g1t.sh/status.json
726- [Support](https://g1t.sh/support): where to get help (hey@flagon.io)
727- [Security](https://g1t.sh/security): how g1t protects code and accounts, and responsible disclosure (hey@flagon.io, https://g1t.sh/.well-known/security.txt)
728- [Policies](https://g1t.sh/policies): [Terms of Service](https://g1t.sh/policies/terms), [Privacy Policy](https://g1t.sh/policies/privacy), [Acceptable Use](https://g1t.sh/policies/acceptable-use), [Refunds and Cancellation](https://g1t.sh/policies/refunds), [Subprocessors](https://g1t.sh/policies/subprocessors)
729- g1t is made by Flagon, Inc. (https://www.flagon.io)