Skip to content
DashboardWebsite

GitLab Integration

Just want to do it in the dashboard? See the guide: Connect GitLab.

This page explains how org admins connect a self-managed GitLab group and how platform admins and project maintainers complete the setup. OpenTremor reviews merge requests after pushes, posts one report note edited in place on each push, and uses a commit status to gate merges while an open CRITICAL/HIGH finding or one waiting for a human remains. Dashboard triage updates that status; suppressing the last blocking finding releases the merge without another push. Reviewers’ notes feed the feedback loop, including the @opentremor commands. The review uses the same pipeline as the GitHub App.

The integration was tested against GitLab CE 19.2 and 19.4, including the Free tier. gitlab.com uses the same API but is not a supported target.

StepWhoWhere
1Platform adminEnable the integration and set its allowed hosts: Platform Admin → Connections → GitLab
2GitLab adminAllow webhooks to reach OpenTremor if it is on the local network
3Group ownerCreate a group access token
4Org adminConnect the group in OpenTremor: Organization → Connections → GitLab
5Project maintainerAdd a webhook to each project and enable Pipelines must succeed

In the dashboard, open Platform Admin → Connections → GitLab:

  • Turn on Offer the GitLab integration.
  • Turn on Allow private network addresses if GitLab runs on the company network.
  • Add the GitLab host under Allowed hosts, for example gitlab.corp.example.

The same settings are available through the API (gitlab):

PATCH /v1/admin/settings
{"gitlab_egress": {"enabled": true, "allow_private_networks": true, "allowed_hosts": ["gitlab.corp.example"]}}

allowed_hosts restricts which hosts an org can connect to. The platform admin controls where the URL may point. The org admin supplies the certificate to trust in step 4. An operator whose orgs use the same company CA can set gitlab.ca_bundle: /path/to/ca.pem in the config file as the default for orgs that do not supply a CA bundle. OpenTremor always verifies certificates.

2. GitLab admin: allow webhooks to reach OpenTremor

Section titled “2. GitLab admin: allow webhooks to reach OpenTremor”

If OpenTremor’s URL resolves to a private address, a GitLab administrator must enable Admin → Settings → Network → Outbound requests → Allow requests to the local network from webhooks and integrations, or add OpenTremor’s host to GitLab’s allowlist.

GitLab may take a few minutes to apply this setting. During that time, deliveries can fail with URL is blocked. GitLab does not retry those deliveries. Wait, then use Test on the webhook before relying on it.

Open Group → Settings → Access tokens → Add new token. Set the role to Developer and the scope to api. Notes and statuses are authored by the token’s bot user (group_<id>_bot_…). GitLab requires an expiry date no more than a year away.

The read_api scope cannot post notes. If you cannot use a group access token, a personal access token for a dedicated bot user also works.

In the dashboard, open Organization → Connections → GitLab. Enter the GitLab URL, access token, and LLM connection. The list shows enabled LLM connections for your org. If none are available, add one under LLM connections first. After connecting, the page shows the webhook URL, the secret once, the token expiry when GitLab provides it, and the project setup steps. The page explains if a platform admin has not enabled GitLab.

If GitLab’s HTTPS certificate comes from a company CA, paste that CA certificate in PEM format into CA certificate. OpenTremor stores it encrypted and does not show it again. When updating the connection, leave the field empty to keep the stored certificate, or select Remove the stored CA certificate.

Or use the API:

Terminal window
curl -X POST "$OPENTREMOR/v1/orgs/$ORG/integrations/gitlab" \
-H "X-API-Key: $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"base_url": "https://gitlab.corp.example", "access_token": "glpat-…",
"connection_id": "anthropic", "model": "claude-sonnet-5"}'

OpenTremor checks the URL against the deployment’s policy and checks the token with GitLab. The response includes a webhook_url and webhook_secret. The secret is returned only on the first connection. Connecting again, for example to rotate the token, keeps the URL and secret. See POST /v1/orgs/{org_id}/integrations/gitlab.

GitLab must be able to reach webhook_url. OpenTremor builds it from server.public_base_url.

5. Project maintainer: add a webhook and merge check

Section titled “5. Project maintainer: add a webhook and merge check”
  1. In Project → Settings → Webhooks → Add new webhook, set the URL to webhook_url. Select Merge request events and Comments. Comments feed the feedback loop. Select Push events to re-read rules from ADRs when the default branch changes. Paste the secret into Secret token or Signing token. The signing token signs each delivery where GitLab supports it. One field is enough.

  2. In Project → Settings → Merge requests → Merge checks, enable Pipelines must succeed. Without this setting, the status appears on the merge request but does not hold the merge. This setting is available on every tier, including Free.

GitLab CE has no group-level webhooks, so add the webhook to each project. The Repositories page lists every project the token can reach. If a project’s Last pull request column says Never, its webhook may be missing. See Review routing.

  • Open, reopen, or push: OpenTremor reviews the merge request. A title or description edit without a push does not trigger a review.
  • Draft: By default, a draft gets a pending status and no note. OpenTremor reviews it when someone marks it ready. To review drafts earlier, enable Draft pull requests in that repository’s settings.
  • Diff: OpenTremor reads GitLab’s raw_diffs, including all files.
  • Report note: The note contains the light report and links to the full report and dashboard findings. OpenTremor escapes model-written text before posting, including text GitLab could run as a quick action (/merge, /close) or turn into a reference (#12, ~label, @all).
  • Commit status: OpenTremor names the status opentremor-core. When the project has a CI pipeline, OpenTremor attaches its status to that pipeline. GitLab ignores a status in a separate pipeline for Pipelines must succeed. An open CRITICAL or HIGH finding sets a failing status; otherwise, a finding waiting for a human sets it to pending. Triage reposts the status against the same commit.
  • Merge request author: OpenTremor trusts an author with Developer access or higher on the target project. If an outside contributor edits an agent instruction file such as CLAUDE.md or .cursorrules, OpenTremor reports it.
  • Reviewer notes: OpenTremor records a person’s note as feedback. It trusts the note when its author has Developer access or higher. A diff note keeps its file and line. A note such as @opentremor false-positive <rule_id> states a verdict.
  • OpenTremor does not rotate the token. token_expires_at gives its expiry when GitLab provides it.
  • GitLab may recompute pipeline status a moment after OpenTremor posts it. A merge clicked within seconds of a status change can pass on the previous state.

If OpenTremor has no public URL or cannot reach GitLab, the merge gate from CI runs inside the pipeline and needs neither.