Onboard a GitLab project
Add a GitLab project to Gitar and configure webhooks for code review. This endpoint is idempotent — calling it for an already-connected project returns success with status already_connected.
Selecting a GitLab instance. Organizations with a single connected GitLab instance can omit host. Once an organization connects more than one instance, host becomes required: without it Gitar cannot tell which instance a project id or path refers to, and the request is rejected with 409 Conflict listing the connected instances.
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")
project_id takes precedence.
Selecting a GitLab instance
If your organization has connected a single GitLab instance, you can omithost 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.
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:- Verify the project exists in the GitLab instance you selected
- Register the project for Gitar code review
- Configure a project-level webhook so Gitar receives push and merge request events
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
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.
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.
GitLab project numeric ID (e.g. 12345)
x >= 0GitLab 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.