---
title: "Onboard a GitLab project"
method: POST
path: "/external/gitlab/projects"
tags: ["GitLab Projects"]
---

# Onboard a GitLab project

`POST /external/gitlab/projects`

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.

## Request body

- OnboardGitlabProjectApiRequest — 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, nullable — 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, nullable — GitLab project numeric ID (e.g. 12345)
  - `project_path` string, nullable — GitLab project path (e.g. "group/subgroup/project")

## Response `200`

Project onboarded successfully or already connected

- OnboardGitlabProjectApiResponse — Response from onboarding a single GitLab project via the external API.
  - `error` string, nullable
  - `project_id` integer, nullable
  - `project_path` string, required
  - `status` 'onboarded' | 'already_connected' | 'failed', required — Status of an individual project onboard operation.
  - `success` boolean, required
  - `webhook_configured` boolean, required

## Other responses

- `400` — Bad request (missing project_id and project_path, or no GitLab integration for this organization)
- `401` — Unauthorized
- `403` — Insufficient scopes
- `404` — Organization not found
- `409` — The organization has several GitLab instances and `host` did not identify one, or the project id is already connected from a different instance

## Changes

- **2026-08-05** `c7d5cd8f5507` — 2 info
  - added the new optional request property `host`
  - added the non-success response with the status `409`

[Change history](https://skmtc.dev/gitar/apis/gitar-external-api/changes/external/gitlab/projects/post.md)

---

[API](https://skmtc.dev/gitar/apis/gitar-external-api.md) · [All operations](https://skmtc.dev/gitar/apis/gitar-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gitar/gitar-external-api/revisions/c7d5cd8f5507/schema)