GitHub Integration
GitHub Integration
Zeeq uses a GitHub App installation to receive webhook events and write review comments, reactions, and review-thread messages. The installation link is organization-scoped inside Zeeq, while repository mappings decide which GitHub repositories are allowed to enter the queue-backed code-review workflow.
Installation Link
An owner or admin starts the install flow from the Zeeq settings UI. The server creates a short-lived protected state token that carries the current Zeeq organization, optional team, user id, nonce, and expiry.
GitHub redirects back to Zeeq with an installation_id and that state token. Zeeq verifies the installation with GitHub App authentication, then stores the canonical local link in GitHubAppInstallation.
The phase-one trust model links a GitHub-verified installation to the Zeeq organization carried by the protected state token. It does not yet prove the Zeeq user controls the GitHub account through a GitHub user access token.
Repository Registration
Webhook ingress does not accept every repository visible to the GitHub App. Operators must register repositories through the GitHub repository management API:
| Endpoint | Purpose |
|---|---|
GET /api/v1/orgs/{orgId}/integrations/github/repositories/configured | Lists active Zeeq repository mappings for the route organization. |
GET /api/v1/orgs/{orgId}/integrations/github/repositories/available | Lists repositories currently visible to the linked GitHub App installation and marks which are already configured. |
POST /api/v1/orgs/{orgId}/integrations/github/repositories | Creates or refreshes a Zeeq repository mapping after validating the repository is visible to the installation. |
PUT /api/v1/orgs/{orgId}/integrations/github/repositories/{repositoryId} | Updates local display, team, and enabled settings for an existing mapping. |
DELETE /api/v1/orgs/{orgId}/integrations/github/repositories/{repositoryId} | Soft-disables a mapping so future webhooks for that repository are ignored. |
The route organization must match the organization in the authenticated Zeeq session. Repository identity uses GitHub owner/name, for example zeeq-ai/zeeq.
Webhook Gate
GitHubWebhookRepositoryGate resolves incoming webhook repository.full_name values against active CodeRepository rows. Missing or disabled mappings are acknowledged as no-op and do not publish queue work.
This gate is intentionally early:
- GitHub delivery is accepted and traced.
- The repository is resolved from
CodeRepository. - Unsupported repositories stop there.
- Supported repositories publish tenant queue messages for PR, PR issue-comment, and PR review-comment workflows.
Command comments have an additional filter. Only PR issue comments or review comments whose first non-whitespace token is /zeeq or +zeeq enter the feedback pipeline.
Durable State
| Model | Role |
|---|---|
GitHubAppInstallation | Organization-scoped GitHub App installation link and token-resolution source. |
CodeRepository | Provider-neutral repository mapping used by webhook ingress and workflow handlers. |
GitHubWebhookDelivery | Idempotent delivery claim record for queue consumers. |
PullRequestRecord | Current PR state used by workflow policy and review creation. |
CodeReviewRecord | Review run state and budget authority. |
GitHubCommentAnchor | Repairable pointer from logical Zeeq comment target to GitHub comment id. |
GitHubCommentLease | Short-lived write lease for serialized GitHub comment updates. |
Repository mappings do not store GitHub installation ids. Installation lifecycle belongs to GitHubAppInstallation; repository mappings only say which provider repository is enabled for a Zeeq organization or team.