flagon-io/g1t

public

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