--- title: "GitLab · API reference · Promigence" description: "The Promigence API's gitlab routes: 7 in all, with parameters, request bodies and answers." url: "https://www.promigence.ai/docs/reference/api/gitlab" site: "Promigence" --- [API reference](https://www.promigence.ai/docs/reference/api) # 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:"`. #### 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](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors)