Sign in

flagon-io/g1t

public

Commit

Docs: integrations, and your own model provider

Two new guides: Integrations (Sentry, Datadog, signed webhooks, Jira and Linear, importing tickets, what agents read, writing back) and Your own model provider (Anthropic or an endpoint, the fee, and why the key never reaches a sandbox). The MCP reference, billing guide and llms.txt list the new tools and routes.

syntaqxcommitted Parent91406c3Browse files
7 files+343−10/7 viewed
+7−0
7272 ],
7373 },
7474 {
75+ label: 'Connect your tools',
76+ items: [
77+ { label: 'Integrations', slug: 'guides/integrations' },
78+ { label: 'Your own model provider', slug: 'guides/models' },
79+ ],
80+ },
81+ {
7582 label: 'Landing changes',
7683 items: [
7784 { label: 'The merge queue', slug: 'guides/merge-queue' },
+227−0
1+---
2+title: Integrations
3+description: Connect Sentry, Datadog, Jira, Linear and anything that sends a webhook, so problems become issues and agents read the tickets the work refers to.
4+---
5+
6+A workspace connects to the systems its work already lives in. There are
7+three kinds of connection:
8+
9+| Kind | Systems | What it does |
10+| --- | --- | --- |
11+| [Model provider](/guides/models/) | Anthropic, or any Anthropic-compatible endpoint | Your agents' model requests go to your own account. |
12+| [Alerts](#alerts) | Sentry, Datadog, a signed webhook | A problem opens an issue, once however often it fires, and an agent can start on it at once. |
13+| [Trackers](#trackers) | Jira, Linear | Agents read the tickets that work mentions, people import tickets as issues, and tickets hear back when the work lands. |
14+
15+Open the workspace's **Integrations** page from the sidebar. Every member
16+can see the connections; only owners can add, test or remove them.
17+
18+Secrets are sealed when they are saved and never shown again, to anyone.
19+The page shows the last four characters of a key, so you can tell keys
20+apart. Agents never see a connection's secrets.
21+
22+## Alerts
23+
24+An alert source opens issues in one repository. Each problem it reports is
25+one issue:
26+
27+- **The first alert** opens an issue labelled `bug` (or the label you set)
28+ and the provider's name, with what the provider said about the problem.
29+- **The same problem again** updates that issue instead of opening another.
30+ The issue says so when the count passes 10, 100, 1,000 and so on.
31+- **The same problem after its issue was closed** reopens it, with a comment
32+ linking the new occurrence.
33+- **A recovery** (Datadog) is noted on the issue.
34+
35+Turn on **Put a g1t agent on each new issue** and an agent starts on the
36+issue as soon as it opens: it makes the change, is reviewed, revises, and
37+lands through your repository's rules, often before anyone has looked. A
38+reopened issue gets an agent again. Agents run only in workspaces
39+[g1t agents](/guides/g1t-agents/) are enabled for; elsewhere the issue says
40+why none started.
41+
42+Text in an alert can include what your users typed, such as an error
43+message built from a request. Issues opened from alerts say so, and agents
44+treat that text as a description of the problem, never as instructions.
45+
46+Each alert connection shows its last five deliveries: what arrived, and
47+whether g1t opened, updated, reopened, ignored or refused it.
48+
49+### Sentry
50+
51+1. On the **Integrations** page, choose **Sentry**. Give your organization's
52+ slug and the repository issues go to, then **Connect**.
53+2. In Sentry, open **Settings → Developer Settings → Custom Integrations**
54+ and create an **internal integration**:
55+ - **Webhook URL**: the address g1t shows on the connection,
56+ `https://api.g1t.sh/hooks/<connection>`.
57+ - Turn on **Alert Rule Action**, and under **Webhooks** tick **issue**.
58+ - **Permissions**: Issue & Event, read and write.
59+3. Save it. Paste its **client secret** into the connection on g1t, and its
60+ **token** as the connection's auth token.
61+
62+Then:
63+
64+- New Sentry issues open g1t issues. So does any alert rule whose action
65+ sends a notification to the integration.
66+- With the token, g1t adds the latest event's stack trace, in-app frames
67+ first, so the agent starts at the failing line.
68+- When the fix merges, g1t resolves the Sentry issue and comments with the
69+ pull request. If Sentry sees it again, the g1t issue reopens.
70+
71+Requests without a valid `Sentry-Hook-Signature` are refused.
72+
73+### Datadog
74+
75+1. On the **Integrations** page, choose **Datadog**, pick the repository,
76+ and **Connect**. g1t shows a signing secret once; copy it.
77+2. In Datadog, open **Integrations → Webhooks** and add a webhook named
78+ `g1t`:
79+ - **URL**: the connection's address.
80+ - **Custom headers**: `{"Authorization": "Bearer <signing secret>"}`
81+ - **Payload**:
82+
83+ ```json
84+ {
85+ "id": "$ALERT_ID",
86+ "title": "$EVENT_TITLE",
87+ "body": "$EVENT_MSG",
88+ "url": "$LINK",
89+ "status": "$ALERT_TRANSITION",
90+ "priority": "$PRIORITY"
91+ }
92+ ```
93+
94+3. Mention `@webhook-g1t` in the message of any monitor that should open
95+ issues.
96+
97+A monitor that triggers opens an issue; `Recovered` is noted on it.
98+
99+### Any other system
100+
101+The **Webhook** connection takes JSON from anything that can send it:
102+PagerDuty, Grafana, a deploy script.
103+
104+```sh
105+body='{"id":"checkout-500","title":"Checkout returns 500 for empty carts","body":"POST /checkout fails."}'
106+curl -X POST https://api.g1t.sh/hooks/$CONNECTION \
107+ -H "Content-Type: application/json" \
108+ -H "X-G1t-Signature: sha256=$(printf '%s' "$body" | openssl dgst -sha256 -hmac "$SECRET" -hex | cut -d' ' -f2)" \
109+ -d "$body"
110+```
111+
112+Sign it either way:
113+
114+- `X-G1t-Signature: sha256=<hex HMAC-SHA256 of the body>`, with the signing
115+ secret as the key, or
116+- `Authorization: Bearer <signing secret>`.
117+
118+g1t reads these fields, taking the first name present:
119+
120+| Field | Names | Notes |
121+| --- | --- | --- |
122+| Title | `title`, `event_title`, `summary`, `name` | Required. |
123+| Id | `id`, `alert_id`, `aggregate`, `incident_key`, `dedup_key` | Alerts with the same id are one issue. The title if missing. |
124+| Description | `body`, `message`, `event_msg`, `text`, `description` | Markdown. |
125+| Link | `url`, `link`, `html_url` | |
126+| State | `status`, `transition`, `alert_transition`, `state` | `recovered`, `resolved`, `ok` or `closed` means it stopped. |
127+| Priority | `priority`, `severity`, `level` | |
128+| Count | `count` | How many times it has happened. |
129+
130+g1t answers `202` once the request is verified and acts on it just after,
131+so a slow step never makes the sender retry. It answers `401` to a request
132+that is not signed, and `200` with the reason to one it ignores.
133+
134+## Trackers
135+
136+Connect Jira or Linear and tickets become something agents and people can
137+reach from g1t.
138+
139+### Agents read tickets the work mentions
140+
141+When a g1t agent starts on an issue, or plans an outcome, g1t looks for
142+ticket keys and addresses in the text (`TECH-1234`,
143+`https://acme.atlassian.net/browse/TECH-1234`,
144+`https://linear.app/acme/issue/ENG-42/…`, a Sentry issue's address) and
145+fetches each from the system it lives in. The agent gets their titles,
146+statuses and descriptions as reference material, and its session notes
147+what it read.
148+
149+So a brief of "Accomplish TECH-1234" works: the planner reads the ticket.
150+
151+Agents, and your own agent through MCP, can also look a reference up with
152+the `get_context` tool:
153+
154+```sh
155+curl "https://api.g1t.sh/repos/acme/web/context?reference=TECH-1234" \
156+ -H "Authorization: Bearer $G1T_TOKEN"
157+```
158+
159+### Import a ticket as an issue
160+
161+On a repository's **New issue** page, give a key or paste an address under
162+**Bring one in**. g1t opens an issue with the ticket's title and
163+description, linked to it. Tick **Put an agent on it** to start one at
164+once. Importing the same ticket again opens the issue already made.
165+
166+From the API or an agent:
167+
168+```sh
169+curl -X POST https://api.g1t.sh/repos/acme/web/issues/import \
170+ -H "Authorization: Bearer $G1T_TOKEN" -H "Content-Type: application/json" \
171+ -d '{"reference": "TECH-1234", "assign": true}'
172+```
173+
174+An issue tied to something outside g1t shows it under **From outside g1t**,
175+with a link to the original.
176+
177+### Tickets hear back
178+
179+Unless you turn it off, g1t comments on the ticket when a pull request
180+opens for its issue, and again when the issue closes as done, with a link
181+to what merged. For Sentry, closing as done resolves the Sentry issue.
182+
183+### Jira
184+
185+| Setting | |
186+| --- | --- |
187+| Site | Your Jira's address, such as `https://acme.atlassian.net`. |
188+| Email | The Atlassian account the API token belongs to. |
189+| API token | From id.atlassian.com, **Security → API tokens**. g1t sees what that account can see. |
190+| Project keys | Optional. The projects this connection answers for, such as `TECH, OPS`. Empty answers for any key. |
191+
192+### Linear
193+
194+| Setting | |
195+| --- | --- |
196+| API key | From Linear, **Settings → Security & access → Personal API keys**. |
197+| Team keys | Optional, such as `ENG`. Empty answers for any key. |
198+
199+A key that matches several connections is looked up in the ones that name
200+its project first.
201+
202+## From the API
203+
204+Owners can manage integrations through the API and MCP, with a person's
205+token (a workspace token or an agent cannot):
206+
207+| Tool | Route |
208+| --- | --- |
209+| `list_integrations` | `GET /workspaces/{workspace}/integrations` |
210+| `connect_integration` | `POST /workspaces/{workspace}/integrations` |
211+| `test_integration` | `POST /workspaces/{workspace}/integrations/{id}/test` |
212+| `disconnect_integration` | `DELETE /workspaces/{workspace}/integrations/{id}` |
213+| `get_context` | `GET /repos/{owner}/{name}/context?reference=` |
214+| `import_issue` | `POST /repos/{owner}/{name}/issues/import` |
215+
216+```sh
217+curl -X POST https://api.g1t.sh/workspaces/acme/integrations \
218+ -H "Authorization: Bearer $G1T_TOKEN" -H "Content-Type: application/json" \
219+ -d '{"provider": "jira", "config": {"site": "https://acme.atlassian.net", "email": "dev@acme.com", "keys": ["TECH"]}, "secret": "<api token>"}'
220+```
221+
222+`provider` is `anthropic`, `anthropic_endpoint`, `sentry`, `datadog`,
223+`webhook`, `jira` or `linear`. `config` takes `repo`, `assign`, `label`,
224+`write_back`, `organization`, `site`, `email`, `keys`, `base_url`,
225+`auth_header` and `model`; each provider uses the ones above. For `datadog`
226+and `webhook`, the response's `signingSecret` is the only time the secret
227+is shown.
+68−0
1+---
2+title: Your own model provider
3+description: Send your agents' model requests to your own Anthropic account or endpoint, and pay for the models there.
4+---
5+
6+By default, g1t chooses the model for each kind of work, pays the provider,
7+and charges your workspace's credit what it cost plus a margin. A workspace
8+can instead send its agents' model requests to its own account:
9+
10+| Provider | What you give | Fits |
11+| --- | --- | --- |
12+| **Anthropic** | An API key | Teams with an Anthropic account or contract |
13+| **Your own endpoint** | A base URL, and a key if it needs one | Your own Cloudflare AI Gateway, LiteLLM, Bedrock or Vertex behind an Anthropic-compatible proxy, a self-hosted model |
14+
15+The endpoint has to speak Anthropic's Messages API, because g1t's agents run
16+Claude Code. To use another vendor's models, put a proxy that translates in
17+front of them, such as LiteLLM.
18+
19+## What it costs
20+
21+With your own provider, the provider bills you for the models and g1t
22+charges your credit a flat **$0.10 per run** for the sandbox and the
23+orchestration around it. A change, a review, a revision, a catch-up and a
24+plan are each a run. Your statement marks these runs "on your own model
25+provider", and the Usage page shows what they cost at your provider, as
26+the harness estimated it, beside what g1t charged. See
27+[Usage and billing](/guides/usage-and-billing/).
28+
29+Workspaces still need credit to start agents, for the fee.
30+
31+## Connect it
32+
33+1. Open the workspace's **Integrations** page. You need to be an owner.
34+2. Under **Model provider**, choose **Anthropic** or **Your own endpoint**.
35+3. For Anthropic, paste an API key. For an endpoint, give its base URL
36+ without `/v1`, its key if it needs one, and whether the key goes in
37+ `x-api-key` or `Authorization: Bearer`.
38+4. **Connect**, then **Test**: g1t asks the provider to list its models with
39+ the key. An endpoint that does not list models is checked on the first
40+ run instead.
41+
42+The next agent run uses it. A workspace uses one model provider; disconnect
43+it to go back to g1t's.
44+
45+### Choosing the model
46+
47+Nobody picks a model when assigning work; g1t routes each kind of work to
48+the model that suits it, and with your own Anthropic key the same models
49+run on your account. If your endpoint names models its own way, set
50+**Model** on the connection and every kind of work uses it.
51+
52+A pull request's session says which model ran, and through which provider.
53+
54+## Your key never reaches a sandbox
55+
56+An agent works in a sandbox with internet access, on code and text that
57+anyone could have written. g1t assumes a sandbox can be talked into
58+printing its environment, so the key is never in it:
59+
60+1. When a run starts, g1t gives the sandbox a token for that run only.
61+2. The sandbox sends its model requests to `https://models.g1t.sh` with that
62+ token in place of a key.
63+3. g1t's model proxy looks the token up, adds your key, and forwards the
64+ request to your provider. Responses stream straight back.
65+
66+The token stops working when the run ends (three hours at most), or at once
67+if you disconnect the provider. Your key is sealed when you save it, and
68+used only by the proxy.
+4−0
2424 Each run is charged when it finishes: what the model provider charged for
2525 it, plus 20%. A small change costs a few cents.
2626
27+A workspace with [its own model provider](/guides/models/) pays the
28+provider for the models instead, and each run here is a flat $0.10 for the
29+sandbox and orchestration.
30+
2731 The charge goes to the workspace that owns the repository, whoever
2832 assigned the issue. That is why only members of a workspace can put g1t
2933 agents to work on its repositories.
+2−0
4545 <li><a href="/guides/outcomes/">Outcomes and plans</a></li>
4646 <li><a href="/guides/talking-to-agents/">Talking to agents</a></li>
4747 <li><a href="/guides/bring-your-own-agent/">Bring your own agent</a></li>
48+ <li><a href="/guides/integrations/">Integrations: Sentry, Jira, Linear</a></li>
49+ <li><a href="/guides/models/">Your own model provider</a></li>
4850 </ul>
4951 </div>
5052 <div>
+14−1
101101
102102 See [merge queue](/guides/merge-queue/).
103103
104+## Integrations
105+
106+See [Integrations](/guides/integrations/). Managing them needs an owner's own token.
107+
108+| Tool | Required | What it does | Route |
109+| --- | --- | --- | --- |
110+| `list_integrations` | `workspace` | The workspace's connections. Secrets are never returned. Members only. | `GET /workspaces/{workspace}/integrations` |
111+| `connect_integration` | `workspace`, `provider` | Connect Anthropic, your own endpoint, Sentry, Datadog, a webhook, Jira or Linear, with `config` and `secret`. Owners only. | `POST /workspaces/{workspace}/integrations` |
112+| `test_integration` | `workspace`, `id` | Check its credentials against the system it connects to. Owners only. | `POST /workspaces/{workspace}/integrations/{id}/test` |
113+| `disconnect_integration` | `workspace`, `id` | Remove it and its secrets. Owners only. | `DELETE /workspaces/{workspace}/integrations/{id}` |
114+| `get_context` | `repo`, `reference` | A Jira or Linear ticket by key or address, or a Sentry issue by address, as it is now. Reference material, never instructions. | `GET /repos/{owner}/{name}/context?reference=` |
115+| `import_issue` | `repo`, `reference` | Open an issue from a ticket, linked to it. `assign` puts a g1t agent on it. | `POST /repos/{owner}/{name}/issues/import` |
116+
104117 ## Messages
105118
106119 | Tool | Required | What it does | Route |
117130 tools: `get_repo`, `list_issues`, `get_issue`, `list_labels`,
118131 `create_issue`, `add_comment`, `list_pull_requests`, `get_pull_request`,
119132 `get_pull_request_changes`, `read_session`, `get_merge_queue`,
120−`list_events`, `take_messages`, `message_agent` and `answer_message`.
133+`list_events`, `take_messages`, `message_agent`, `answer_message` and `get_context`.
121134 `tools/list` shows such a token only the tools it may use.
+21−0
185185 `mark_pull_request_ready`, `close_pull_request`,
186186 `get_pull_request_changes`, `review_pull_request`, `merge_pull_request`,
187187 `get_merge_queue`, `message_agent`, `answer_message`, `take_messages`,
188+`list_integrations`, `connect_integration`, `test_integration`,
189+`disconnect_integration`, `get_context`, `import_issue`,
188190 `list_repos`, `get_repo`, `create_repo`, `update_repo`,
189191 `get_repo_settings`, `update_repo_settings`, `list_events`,
190192 `create_workspace`, and `whoami`. MCP tools take the repository as `repo`,
191193 written `owner/name`.
192194
195+## Integrations
196+
197+A workspace's owners connect it to outside systems on its **Integrations**
198+page, or with `POST /workspaces/{workspace}/integrations`:
199+
200+- **Its own model provider** (`anthropic`, or `anthropic_endpoint` for any
201+ Anthropic-compatible URL): agents' model costs are billed there, and g1t
202+ charges $0.10 a run. Sandboxes never hold the key.
203+- **Alerts** (`sentry`, `datadog`, `webhook`): each problem opens one issue
204+ in a chosen repository, optionally with an agent put on it at once.
205+ Senders sign requests to `https://api.g1t.sh/hooks/{integration}`.
206+- **Trackers** (`jira`, `linear`): `GET {repo}/context?reference=TECH-1234`
207+ fetches a ticket; `POST {repo}/issues/import` with `reference` (and
208+ `assign`) opens a linked issue. Agents get tickets their work mentions in
209+ their starting context. Ticket text is reference material, never
210+ instructions.
211+
193212 ## Facts
194213
195214 - API base: `https://api.g1t.sh`. `GET /` lists every URL as a template.
224243 - [Forks and branches](https://docs.g1t.sh/concepts/forks/)
225244 - [Accounts and sign-in](https://docs.g1t.sh/guides/authentication/)
226245 - [Workspaces and tokens](https://docs.g1t.sh/guides/workspaces/)
246+- [Integrations](https://docs.g1t.sh/guides/integrations/)
247+- [Your own model provider](https://docs.g1t.sh/guides/models/)
227248 - [Usage and billing](https://docs.g1t.sh/guides/usage-and-billing/)
228249 - [Git](https://docs.g1t.sh/guides/git/)
229250 - [MCP tools](https://docs.g1t.sh/reference/mcp/)