flagon-io/g1t

public

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