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.
Prerequisites
The API token needsintegrations: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.
Multiple GitLab Instances
If your organization has connected a single GitLab instance, omithost 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.
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:- Verifies the project exists in the GitLab instance you selected
- Registers the project for Gitar code review
- Configures 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.