GitLab

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

GET/v1/integrations/gitlab

Auth: API key

Your organization's GitLab connections (each with the URL and token of an optional project webhook that makes tracked branches build at once), the ones waiting for an owner to confirm, and the snapshots that follow a branch. configured: false on a deployment with no GitLab application.

Parameters

claimquery · string
codequery · string
errorquery · string
statequery · string

Answer 200 · GitlabStatus · application/json

configuredrequiredboolean: False on a deployment with no GitLab application: nothing here works there, and message says so.
connectionsrequiredGitlabConnection[]
gitlab_urlstring | null
messagestring | null
pendingrequiredGitlabPending[]
tracksrequiredGitlabTrack[]

POST/v1/integrations/gitlab/connect

Auth: API key

Start connecting a GitLab user: a link to authorize the platform's GitLab application, read-only (read_api read_repository), valid for 15 minutes. Open it in a browser and authorize; then an owner of your organization confirms it, signed in to Promigence in that same browser. GET /v1/integrations/gitlab then lists the connection. Body: {}.

Parameters

claimquery · string
codequery · string
errorquery · string
statequery · string

Answer 200 · GitlabConnect · application/json

authorize_urlrequiredstring: GitLab's authorization page, carrying a signed state that names this organization.
expires_atrequiredstring: When the link stops working (RFC 3339): 15 minutes.
gitlab_urlrequiredstring: The GitLab the connection is made on (https://gitlab.com).
scopesrequiredstring[]: What the application asks for: read-only access.

DELETE/v1/integrations/gitlab/connections/{connection_id}

Auth: API key

Disconnect a GitLab user: the authorization is revoked on GitLab, nothing is built from it any more and the snapshots that followed branches through it stop following them.

Parameters

connection_idrequiredpath · string

Answer 200 · GitlabDisconnected · application/json

connection_idrequiredstring
disconnectedrequiredboolean: Always true here.
messagerequiredstring
revokedrequiredboolean: Our token was revoked on GitLab. False when GitLab did not answer: then remove the application under your GitLab user settings > Applications.
tracks_removedrequiredinteger: Snapshots that followed a branch through this connection, and follow nothing now.
usernamerequiredstring

GET/v1/integrations/gitlab/repos

Auth: API key

The projects a GitLab connection can read (the oldest working one unless connection_id names another), one page at a time (page, per_page up to 100). path is what POST /v1/snapshots takes as repo: "gitlab:<path>".

Parameters

claimquery · string
codequery · string
connection_idquery · string
errorquery · string
pagequery · string
per_pagequery · string
statequery · string

Answer 200 · GitlabRepos · application/json

has_morerequiredboolean
pagerequiredinteger: 1-based.
per_pagerequiredinteger
reposrequiredGitlabRepo[]

POST/v1/integrations/gitlab/requests

Auth: API key

Start connecting a GitLab user 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 GitLab, and GET /v1/integrations/gitlab/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: use POST /v1/integrations/gitlab/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/gitlab/requests/{request_id}

Auth: API key

How a GitLab connection request you started ended: pending, then connected, already_connected, declined, 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/gitlab/tracks/{track_id}

Auth: API key

Stop a snapshot following its GitLab branch. The snapshot stays; new commits no longer build it.

Parameters

track_idrequiredpath · string

Answer 200 · GitlabUntracked · application/json

aliasrequiredstring
branchrequiredstring
reporequiredstring
track_idrequiredstring
untrackedrequiredboolean: Always true here.

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