Skip to main content
POST
/
external
/
gitlab
/
projects
Onboard a GitLab project
curl --request POST \
  --url https://api.gitar.ai/v1/external/gitlab/projects \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "project_id": 1,
  "project_path": "<string>"
}
'
{
  "project_path": "<string>",
  "status": "onboarded",
  "success": true,
  "webhook_configured": true,
  "error": "<string>",
  "project_id": 1
}

​
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.

​
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 your connected GitLab instance
  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.

​
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