GitHub

7 routes of the published API contract, generated from it.

GET/v1/integrations/github

Auth: API key

Your organization's GitHub connections, the ones still being finished, and the snapshots that follow a branch. configured: false when GitHub connections are not available.

Answer 200 · GithubStatus · application/json

app_slugstring | null
configuredrequiredboolean: False when GitHub connections are not available: nothing here works then, and message says so.
connectionsrequiredGithubConnection[]
messagestring | null
pendingrequiredGithubPending[]
tracksrequiredGithubTrack[]

POST/v1/integrations/github/connect

Auth: API key

Start connecting a GitHub account: a link to install the platform's GitHub App on it, valid for 15 minutes. Open it in a browser, choose all repositories or selected ones, and GitHub sends you back; GET /v1/integrations/github then lists the connection. The App reads repository contents and metadata, nothing else. Body: {}.

Answer 200 · GithubConnect · application/json

app_slugrequiredstring: The App's name on GitHub (github.com/apps/<slug>).
expires_atrequiredstring: When the link stops working (RFC 3339): 15 minutes.
install_urlrequiredstring: GitHub's install page for the App, carrying a signed state that names this organization.

DELETE/v1/integrations/github/installations/{installation_id}

Auth: API key

Disconnect a GitHub account: nothing is built from it any more and the snapshots that followed its branches stop following them. The App stays installed on GitHub until you uninstall it there (uninstall_url).

Parameters

installation_idrequiredpath · string

Answer 200 · GithubDisconnected · application/json

accountrequiredstring
disconnectedrequiredboolean: Always true here.
installation_idrequiredinteger
messagerequiredstring
tracks_removedrequiredinteger: Snapshots that followed a branch of this account, and follow nothing now.
uninstall_urlrequiredstring: The App stays installed on the GitHub account until it is uninstalled there.

GET/v1/integrations/github/repos

Auth: API key

The repositories your GitHub connections can read, one page at a time (page, per_page up to 100). full_name is what POST /v1/snapshots takes as repo: "github:<full_name>".

Parameters

pagequery · string
per_pagequery · string

Answer 200 · GithubRepos · application/json

has_morerequiredboolean
pagerequiredinteger: 1-based.
per_pagerequiredinteger
reposrequiredGithubRepo[]
totalrequiredinteger: Repositories across every connection.

POST/v1/integrations/github/requests

Auth: API key

Start connecting a GitHub account in the console, for yourself: a one-time ticket (5 minutes) and the console page that uses it (connect_url). Open the page in a browser signed in to the console as you, an owner of this organization; it takes you to GitHub, and GET /v1/integrations/github/requests/{request_id} then says how it ended. The page starts nothing for anyone else: opened while signed in to another account, the request ends as wrong_user. Owners only, like connect. 404 where the console cannot start it for this key (no console here, or a key with no person behind it): use POST /v1/integrations/github/connect. Body: {}.

Answer 201 · ConnectTicket · application/json

connect_urlrequiredstring: The console page that starts the connection: it carries the ticket and nothing else.
expires_atrequiredstring: When the ticket stops working (RFC 3339): 5 minutes.
request_idrequiredstring: The connection request it starts (icr_ and 32 hex digits).
ticket_idrequiredstring: ict_ and 32 hex digits: used once, by you only, within 5 minutes.

GET/v1/integrations/github/requests/{request_id}

Auth: API key

How a GitHub connection request you started ended: pending, then connected, updated (already connected; its repository access changed), pending_provider_approval (an owner of the account must approve it on GitHub first), declined, other_org, needs_admin, not_installer, wrong_user, expired or failed, with a sentence that says what happened and what to do next. Only the person who started it reads it; anyone else gets 404.

Parameters

request_idrequiredpath · string

Answer 200 · ConnectRequest · application/json

accountstring | null: The account on the code host, once it is known.
created_atrequiredstring: RFC 3339.
finished_atstring | null: RFC 3339: when it ended; absent while it is pending.
messagerequiredstring: One or two sentences for a person: what happened, then what to do next.
providerrequiredstring: github or gitlab.
request_idrequiredstring: icr_ and 32 hex digits.
staterequiredstring: pending while it is not finished; then how it ended: connected, updated (already connected to this organization; its repository access changed), already_connected, pending_provider_approval (an owner of the account must approve it on the code host first), declined, other_org (connected to another organization), needs_admin, not_installer, wrong_user (the connection page was opened signed in to another account), expired or failed.

DELETE/v1/integrations/github/tracks/{track_id}

Auth: API key

Stop a snapshot following its branch. The snapshot stays; pushes no longer build it.

Parameters

track_idrequiredpath · string

Answer 200 · GithubUntracked · application/json

aliasrequiredstring
branchrequiredstring
reporequiredstring
track_idrequiredstring
untrackedrequiredboolean: Always true here.

Every route · what each error means and whether it was billed