Gitops

Receive a GitHub App webhook delivery.

Order matters and matches §7.2: signature verified before anything else is parsed; replay-checked next (so a redelivery of an already-accepted payload is acknowledged, not reprocessed, without needing to re-parse or re-match it); only then is the body parsed and matched to a connection.

Header Parameters

Response Body

Return {"files": {...}, "excluded_kinds": {...}}.

files covers every exportable Kind currently registered (Organization, Monitor, Tag, Rule — see import_service.py's module docstring for why the list stops there). excluded_kinds is a per-Kind live-resource count for every Kind this import cannot express yet (import_service.EXCLUDED_KINDS), so the caller can tell the customer what a snapshot silently leaves out rather than letting an incomplete inventory pass as a complete one.

Response Body

The org's connection, or 404 when it has none.

Response Body

Delete the org's connection (#974: "a connection created by mistake ... is permanent" — there was no route for this at all, for Projects).

Deleting the connection does not delete anything it previously applied (monitors, etc.) — those belong to the org directly (§7.1) and are unaffected. It also does not touch the GitHub App installation underneath it — disconnecting the installation itself is a separate action (DELETE /me/gitops/github/installations/{id}, gitops_github_install.py).

Response Body

Create-or-replace the org's connection. service_account_id is required (no default) — §7.4: "a connection cannot be created without an explicit choice."

400 when service_account_id doesn't resolve to an active account in this org (GitOpsConnectionValidationError); 409 when this (installation_id, repo) pair is already bound to a different org's connection (gitops_connection's own uniqueness constraint — see app/models/gitops_connection.py).

Response Body

Sync runs for the active organization, newest first.

Query Parameters

Response Body

One run plus its resource outcomes, in plan/apply order. 404 across tenants — see module docstring.

Path Parameters

Response Body

The run's event log, oldest first. 404 across tenants — the run lookup is the same org-scoped check get_sync_run uses, so an events request for another org's run never even reaches the events query.

Path Parameters

Query Parameters

Response Body

Mint a state bound to the caller's org and return the GitHub App installation URL — the console sends the browser there (window.location.assign), matching billing.py's create_portal_session {"url": ...} + redirect precedent.

503 when GITHUB_APP_SLUG isn't configured — a deployment-configuration gap, not a caller error, matching GitHubConfigurationError's existing use for the App id/private key in providers/github/client.py.

Response Body

Confirm a GitHub App installation once the console's own Setup URL route has received GitHub's redirect (§7.4). Called server-side by console/app/src/routes/api/gitops/github/setup.ts with this session's bearer attached — never by the browser directly.

Every failure raises a plain HTTPException whose detail is one of a fixed set of short codes (missing_state, invalid_state, org_mismatch, missing_installation, not_configured, github_error) — the console route maps these to github_install_error=<code> on its own redirect, the same shape the old public callback used, and the settings page already renders a message per code (INSTALL_ERROR_MESSAGES).

Response Body

What GitHub App installation this org's connection is bound to, and its live state (#974, GITOPS_ARCHITECTURE.md §7.4). Closes the gap the settings page has today: nothing tells an admin an installation exists, which account it belongs to, whether it covers "all repositories" or a named subset, or whether GitHub has suspended it.

How this learns which installation exists, and why: the candidate installation id is whatever installation_id this org's own gitops_connection row records — there is no separate installations table, and this deliberately does not add one. GitHub's own installation-listing endpoint (GET /app/installations) is App-wide, not org-scoped — it would return every installation of this deployment's App across every customer, which this endpoint has no business exposing to one org's admin. gitops_connection is the only thing this backend already persists that ties an installation to a specific org, so it is the correct (and only safe) source for "which installation does this org have," and its live details (account, repository_selection, suspended_at, current repos) are then fetched fresh from GitHub — never cached, since a stale "installed" reading is exactly what #974 reports as missing today.

Returns a list of zero or one entries — #995 collapsed "an org's Projects, each possibly on a different installation" into "an org has at most one connection, therefore at most one installation." Kept as a list (rather than an Optional[GitOpsInstallationResponse]) so the console's existing rendering, built for a list, needs no reshaping (#996).

An installation GitHub can't be asked about — deleted, or simply fake test data, like the dev org's installation_id=99999002 #974 itself names — comes back with reachable=False rather than failing outright.

Response Body

Disconnect (uninstall) a GitHub App installation (#974).

Semantics decided here, not left to the button: uninstalling on GitHub's side (DELETE /app/installations/{id}) is destructive and irreversible from this side. Rather than delete or orphan the org's connection as a side effect, this route refuses the disconnect outright while the caller's org's connection still references the installation (409) — the admin removes the connection first (DELETE /me/gitops/connection), an explicit, reviewable action, and only then can disconnect the now-unreferenced installation. This is the conservative option GITOPS_ARCHITECTURE.md leaves open rather than settles: it never silently breaks the org's sync, at the cost of one extra step when a real installation removal is intended.

Org-scoped the same way connection creation/deletion are: only the caller's org's connection counts toward the block, so this cannot be used to discover or affect another org's binding to the same installation id.

Path Parameters

Response Body

Mint a state token bound to the caller's org, tagged purpose="source_repo_connection", and return the GitHub App installation URL — the same mechanism gitops_github_install.py's start_github_install uses for the GitOps connection flow (§7.4: "They can also share the connect mechanism ... precisely so a second, source_repo_connection-purposed flow can mint and consume its own state through the same code").

The Setup URL callback (POST /me/gitops/github/setup, gitops_github_install.py) is shared, unmodified. It resolves an installation's repos regardless of which purpose minted its state because it never checks purpose at all — see this module's own docstring and providers/github/install_state.py's for why that is currently harmless (the real gate is require_admin_or_above on the write endpoints, not this token).

Response Body

Response Body

Connect a repo. Creates only a source_repo_connections row — no gitops_connection row, no service account requirement (§7.4).

409 when repo is already connected for this org (UNIQUE(org_id, repo)).

event_families (#1004) is optional; omitting it preserves the safe default (no source_repo_deployment_configs row, nothing ingested).

Response Body

Path Parameters

Response Body

Set (replace) which GitHub deployment event families this connection ingests (#1004) — the write path app/services/gitops/ deployment_ingest.py's read (_get_enabled_families) has had no counterpart until now. A non-empty event_families upserts the source_repo_deployment_configs row; event_families: [] deletes it (never stores an empty-array row — see SourceRepoConnectionService's module docstring) without deleting the connection itself.

404 when connection_id doesn't resolve to a connection in this org. 422 when event_families contains anything other than deployment, workflow_run, or release — validated at the schema layer (app/schemas/source_repo_connection.py), not left to the database CHECK constraint alone.

Path Parameters

Response Body

Disconnect a repo. Cascades its service mappings (ON DELETE CASCADE).

Path Parameters

Response Body

Map service_name to this connection's repo.

404 when connection_id doesn't resolve to a connection in this org. 409 when service_name is already mapped to a different connection in this org — checked at this layer, not a database constraint, since the uniqueness spans connections (see app/services/gitops/source_repo_service.py's module docstring). Also 409 on the (same-connection) UNIQUE(source_repo_connection_id, service_name) database constraint, for a duplicate mapping onto the same connection.

Path Parameters

Response Body

Path Parameters

Response Body