g1t/apps/docs/src/content/docs/guides/integrations.md
| 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 providers](/guides/models/) | Anthropic, OpenAI, Google Gemini, xAI, Mistral, DeepSeek, Azure OpenAI, OpenRouter, Groq, Together AI, Fireworks AI, Cerebras, and any Anthropic- or OpenAI-compatible endpoint | Your agents' model requests go to your own accounts, routed by kind of work. | |
| 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 **Settings → Integrations**. 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 need a way to reach a model: |
| 39 | [your own provider](/guides/models/), or g1t's hosted models where they are |
| 40 | open. Without one, the issue says why no agent 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 `search` tool's `ticket` action: |
| 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 | | MCP tool and action | Route | |
| 208 | | --- | --- | |
| 209 | | `workspace` `list_integrations` | `GET /workspaces/{workspace}/integrations` | |
| 210 | | `workspace` `connect_integration` | `POST /workspaces/{workspace}/integrations` | |
| 211 | | `workspace` `test_integration` | `POST /workspaces/{workspace}/integrations/{id}/test` | |
| 212 | | `workspace` `disconnect_integration` | `DELETE /workspaces/{workspace}/integrations/{id}` | |
| 213 | | `search` `ticket` | `GET /repos/{owner}/{name}/context?reference=` | |
| 214 | | `issue` `import` | `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 one of the [model providers](/guides/models/#from-the-api), |
| 223 | or `sentry`, `datadog`, `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 `signing_secret` is the only time the secret |
| 227 | is shown. |