Skip to main content
POST
Onboard a GitLab project

Prerequisites

The API token needs integrations:write scope. The connected GitLab account must be a Maintainer or higher on the project you want to onboard. Without that access the request fails. See Connect GitLab for setup instructions.

Project Identification

Identify the project by numeric ID or by path. If both are provided, project_id takes precedence.
A project’s numeric ID appears on its GitLab settings page, and in the GitLab API response for GET /api/v4/projects/:id.

Multiple GitLab Instances

If your organization has connected a single GitLab instance, omit host and Gitar uses it. Once your organization connects more than one instance, host becomes required. GitLab project IDs and paths are only unique within one instance, so without a host Gitar cannot tell which instance you mean. A request that omits host, or names a host you have not connected, is rejected with 409 Conflict and the response lists your connected instances.
Connecting the same project from two instances is supported. GitLab assigns it a separate ID on each, so Gitar tracks them separately. This is the normal case while migrating between instances.Two different projects that happen to share a numeric ID across two of your instances are not supported. Onboarding the second one returns 409 Conflict naming the instance that already holds the ID.

Idempotent Behavior

Calling this endpoint repeatedly for the same project is safe. If the project is already connected to Gitar, the response returns "status": "already_connected" rather than creating a duplicate.

What This Endpoint Does

When you onboard a project, Gitar:
  1. Verifies the project exists in the GitLab instance you selected
  2. Registers the project for Gitar code review
  3. Configures a project-level webhook so Gitar receives push and merge request events

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request to onboard a single GitLab project via the external API.

One of project_id or project_path must be provided. If both are present, project_id takes precedence.

host
string | null

GitLab instance the project lives on (e.g. "https://gitlab.com").

Optional for organizations with a single connected GitLab instance, and required once there is more than one — without it the project would be looked up on an arbitrary instance. A request that omits or misnames the host on a multi-instance organization is rejected with 409 Conflict listing the connected instances.

project_id
integer<int64> | null

GitLab project numeric ID (e.g. 12345)

Required range: x >= 0
project_path
string | null

GitLab project path (e.g. "group/subgroup/project")

Response

Project onboarded successfully or already connected

Response from onboarding a single GitLab project via the external API.

project_path
string
required
status
enum<string>
required

Status of an individual project onboard operation.

Available options:
onboarded,
already_connected,
failed
success
boolean
required
webhook_configured
boolean
required
error
string | null
project_id
integer<int64> | null
Required range: x >= 0