GitLab

The mechanics that GitLab shares with GitHub (auto-linking by identifier, the linked-request panel, manual linking by URL, status automation, the branch-name helper, and the outbound completion comment) are documented once in Git linking, status sync, and branch names. This page covers what is specific to GitLab: the OAuth app, connecting a workspace, linking a project, and the issue and comment mirror.

What it does

• Issue mirror: when you link a GitLab project, Ithura imports the first page of its open issues. New GitLab issue events keep the mirrored Ithura issues in sync (title and description always; close maps the issue to a Done-group state, reopen maps it back to a Todo-group state). An issue seen for the first time through a webhook is created in Ithura on the spot.
• Comment mirror: GitLab note events append as comments on the matching Ithura issue.
• Merge request linking: merge_request events link MRs to issues and drive status the same way GitHub PRs do (open or reopen moves the issue to In Progress, merge to Done, close without merge to Cancelled, per your mapping).
• Manual linking: link a merge request to an issue by pasting its URL (.../-/merge_requests/42), and unlink with one click. An issue can carry several linked MRs at once.

Connect (workspace admin)

Workspace settings -> Integrations -> GitLab card -> Connect GitLab. This starts the OAuth install (Admin role required) and, on return, stores the encrypted access token for the workspace. If you see "GitLab is not configured on this instance", the integration has not been enabled for your instance yet.

The connection, once made, is what powers project linking and the issue and comment mirror.

Link a GitLab project (project admin)

A project admin links one GitLab project to one Ithura project. Linking:

1. Records the GitLab project against the Ithura project.
2. Mints a per-link webhook token and returns it once.
3. Imports the first page of the GitLab project's open issues into Ithura (issues plus their sync mapping). The import is one-shot; the webhook takes over from there.

Then add a webhook in the GitLab project pointing back at Ithura:

GitLab webhook field	Value
URL	https://<api-host>/webhooks/gitlab/<token>/
Secret token	the same <token>
Triggers	Issues events, Comments (note) events, Merge request events

Ithura matches the token in the URL against the linked project and verifies it against the X-Gitlab-Token header, so both must carry the same value.

Using it

• Linking a project imports its open issues (first page only) into Ithura.
• After the webhook is in place, GitLab issue, note, and merge request events keep the mirror and the MR links current.
• Put an issue identifier such as PAR-123 in an MR branch or title (or copy a ready-made branch name from the issue) and Ithura links the MR automatically.
• To link a merge request that already exists, paste its URL on the issue.

For the full behavior of linking, status sync, branch names, and the completion comment, see Git linking, status sync, and branch names.

Self-managed / Enterprise GitLab

Ithura runs against gitlab.com by default, but the same integration works with any self-managed or GitLab Enterprise instance you can reach from your Ithura deployment. Two things pin the connector to your instance:

• Base URL — set the GITLAB_BASE_URL instance configuration (Admin → Integrations → GitLab). If you'd rather carry it via environment, the GITLAB_HOST env variable on the API deploy is used as the fallback when no instance-config row exists. Either way, drop the trailing slash and use HTTPS (https://gitlab.example.com, not https://gitlab.example.com/).
• OAuth application — register the app on your instance at Admin Area → Applications, not on gitlab.com. The redirect URI, scopes, and Client ID / Secret you paste back into Ithura's Admin → Integrations page all live on your own instance.

Reachability

The two directions of traffic to keep in mind:

1. Ithura → GitLab for OAuth code exchange, project listing, and installing the webhook. Whatever host you configure needs to be reachable from the Ithura API pod. On restricted networks make sure the API pod's outbound allowlist includes your GitLab host.
2. GitLab → Ithura for webhook deliveries. GitLab has an Outbound requests → Allow requests to local network setting that gates webhooks to non-public hosts. If your Ithura API is at a private address, flip that on OR expose the API through a reverse proxy at a public host. The webhook URL Ithura writes into GitLab is derived from your API's canonical host, so the connector card copy is honest about what the URL will look like.

TLS

Self-signed certificates on the GitLab side are not trusted by default. If your instance uses a private CA, add its root to the container's trust store (mount into /etc/ssl/certs/ on the API image) so both the OAuth exchange and the outbound API calls succeed.

Scope caveat

This ticket ships the connector-level scope: base URL threading, OAuth, project listing, issue/comment/MR webhook sync, and MR linking. Deeper Enterprise flows (self-managed SCIM provisioning, admin-consent install, per-group audit surfaces) are not part of this pass — they land as their own tickets.

Troubleshooting

• Nothing mirrors after linking: confirm the webhook is enabled in GitLab and the token in the URL matches the Secret token field exactly.
• Only the initial import worked: the initial import pulls the first page of open issues; ongoing sync depends on the webhook, so verify GitLab shows successful deliveries.
• 401 or token mismatch: re-link the project to mint a fresh webhook token and update GitLab.
• The OAuth return fails or you see "GitLab is not configured on this instance": the integration has not been enabled for your instance yet.