Skip to main content
POST
Onboard a GitLab project

Idempotent Behavior

This endpoint is safe to call multiple times for the same project. If the project is already connected to Gitar, the response will return "status": "already_connected" instead of creating a duplicate.

Project Identification

You can identify the project to onboard using either:
  • project_id — the numeric GitLab project ID (e.g. 12345)
  • project_path — the full path of the project (e.g. "my-group/my-project")
If both are provided, project_id takes precedence.
You can find a project’s numeric ID on its GitLab settings page, or via the GitLab API at GET /api/v4/projects/:id.

Selecting a GitLab instance

If your organization has connected a single GitLab instance, you can omit host and Gitar will use 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.What is not yet supported is two different projects that happen to share a numeric ID across two of your instances. Onboarding the second one returns 409 Conflict naming the instance that already holds the ID.

Prerequisites

The Gitar service account must be a Maintainer (or higher) on the project you want to onboard. If the service account doesn’t have access, the request will fail. See Connect GitLab for setup instructions.

What This Endpoint Does

When you onboard a project, Gitar will:
  1. Verify the project exists in the GitLab instance you selected
  2. Register the project for Gitar code review
  3. Configure 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