# Integrations Repo admins manage integrations at `///settings/integrations`. Org owners manage them at `/orgs//integrations`, and org integrations receive events from every repo in the org. ## How delivery works - Forge events (`emitWebhook`) are fanned out on the `gitfor-integrations` queue. Failed deliveries retry with exponential backoff (15 s doubling, capped at 1 h). After 7 attempts (6 retries) a delivery moves to `gitfor-integrations-dlq` and is marked `dead` in the delivery log. - Permanent failures (most 4xx, missing credentials, rejected URLs) are logged as `failed` and not retried. - Every outbound URL goes through `assertPublicHttpsUrl` (hostname rules) and then `assertResolvesPublic` (`src/server/net/resolve-guard.ts`), which does DNS-over-HTTPS A/AAAA lookups (following CNAMEs) and rejects private, loopback, link-local, CGNAT, metadata, multicast and reserved addresses, including IPv4-mapped, NAT64 and 6to4 forms. The check runs before every request; redirects are never followed. DoH outages fail closed with a retryable error. - **TOCTOU:** Workers' `fetch()` cannot pin a connection to the checked address, so a DNS-rebinding window remains between the lookup and Cloudflare's own resolution. Answers are cached for 60 s per isolate so repeated checks agree, and Workers egress cannot reach RFC 1918, loopback or metadata addresses anyway. - Deliveries are idempotent per (source event, integration): retried events reuse the same delivery row, and a short lease stops two consumers sending the same delivery. Slack bot posts track each channel, so a retry only resends to channels that failed. Relayed GitHub webhooks are keyed by `X-GitHub-Delivery`, so GitHub's own "Redeliver" of an already-processed delivery is ignored. - Each delivery is metered once when it reaches its final outcome (`ops.integration_deliveries`, per owning account, idempotency key `integration:`) into `integration_usage_daily` until the usage-metering service lands. - Git imports and ref syncs (`src/server/git/relay.ts`) use the same DNS check on every hop, with no loopback escape. a 256 KB request cap and a 64 KB response cap. - Each payload is signed with the integration's secret in `X-Gitfor-Signature-256: sha256=`. - Credentials (webhook URLs, OAuth tokens, signing secrets) are stored AES-GCM encrypted with `SECRETS_KEY`. ## Keeping noise down Integrations are quiet by default: - Only pull requests and releases are on. - CI only reports failures. - Pushes and CI only report the default branch. - Drafts and bots are skipped. Each integration has per-event toggles, branch globs, and a digest mode that batches events into one message every N minutes. The digest is flushed by the 5-minute cron. ## Providers and secrets | Provider | Secrets | Notes | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Slack | `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, `SLACK_SIGNING_SECRET` | OAuth install (`chat:write,commands,incoming-webhook`) or a pasted incoming webhook. Each channel gets its own event filter. The slash command `/gitfor status owner/repo` is served at `/integrations/hooks/slack/commands`. | | Google Chat | none | Paste a space webhook (`chat.googleapis.com`). Messages are sent as `cardsV2`. | | Linear | `LINEAR_CLIENT_ID`, `LINEAR_CLIENT_SECRET` | Issue keys (`ENG-123`) in PR titles, branches and commits link PRs and commits to issues. On PR open, merge or close, the issue moves to the configured state, and is never moved backwards. A signed Linear webhook is registered automatically at `/integrations/hooks/linear/`. | | GitHub | `GITHUB_APP_ID`, `GITHUB_APP_SLUG`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_APP_CLIENT_ID`, `GITHUB_APP_CLIENT_SECRET`, `GITHUB_APP_WEBHOOK_SECRET` | Authenticates with GitHub App installation tokens only. Enable "Request user authorization during installation" so ownership of the installation can be verified. Supports a one-way mirror in either direction, a one-shot import of issues and PRs, and webhook relay. The app webhook URL is `/integrations/hooks/github`. | | Webhook | none | Signed JSON with `{ event, summary, payload }`. | Notes on the GitHub integration (for a token-based, bidirectional mirror with any forge, see [mirroring.md](mirroring.md)): - The GitHub → gitfor mirror runs at most every 15 minutes, and also runs on each relayed GitHub push. - Mirrors cover branches and tags only. - Mirrors update and create refs but never delete them. - The GitHub → gitfor mirror goes through the same gates as a git push, acting as a write-permission pusher (the installing admin): hidden refs are never written, branch protection applies (so a branch that requires pull requests is never updated by the mirror, and a protected branch only accepts a non-fast-forward when its rule allows force pushes), and push protection scans for secrets. Applied refs fire normal push events, so CI, webhooks and integrations run. - By default the mirror is fast-forward only. **Force mirror** is an explicit per-integration admin opt-in that lets diverged unprotected branches be overwritten (it never relaxes push protection); enabling or disabling it (and changing the mirror direction) is recorded in the integration's audit log and shown in the UI. Refused refs are listed in the delivery log. - Only repositories that the installing GitHub user could access through the installation can be chosen. - PRs are imported as issues labelled `pull-request`, since their branches are not copied. - Re-running an import skips items that were already imported. ## Local development and e2e Add `INTEGRATIONS_ALLOW_LOOPBACK=true` to `.dev.vars` to allow `http://localhost` and `127.0.0.1` sinks. Never set it in production. Then run: ```sh bun test src E2E_BASE_URL=http://localhost:3000 bun run test:e2e:integrations ``` The e2e flow: 1. Signs up and creates an org. 2. Checks that a private-network URL is rejected. 3. Adds a webhook integration that points at a local sink. 4. Sends a test event and verifies its HMAC signature. 5. Waits for the delivery log to show success, then redelivers.