This guide walks through setting up MergeHarbor on GitLab, from the first connection to a merge gate that can stop a merge request that is not ready. It covers GitLab.com and GitLab Self-Managed. Most teams finish the connection in a few minutes; the rest of the guide is about the choices that make reviews useful once they arrive.
If you only want the reference, the GitLab docs page is shorter. For an overview of what MergeHarbor does on GitLab, see AI code review for GitLab.
Before you start
You need three things:
- A MergeHarbor organization. Sign up at app.mergeharbor.com/signup with GitLab, another code host, or an email address. Every new organization gets the Team plan free for 14 days, with no card.
- Access to the GitLab projects you want reviewed. Either a GitLab account that can authorize an OAuth application on those projects, or a group or project access token (see below).
- For GitLab Self-Managed, the instance URL, and an answer to one question: can MergeHarbor reach your instance from the internet? If it cannot, read Private networks first.
Step 1: choose how to connect
MergeHarbor connects to GitLab in one of two ways. Both end in the same place: MergeHarbor stores the credentials encrypted and registers a webhook on each project you enable.
Connect with GitLab (OAuth, recommended)
- In the console, open Integrations → Code hosts and choose GitLab, or GitLab Self-Managed and enter your instance URL.
- Authorize MergeHarbor on GitLab.
- Choose the projects to review.
With OAuth, MergeHarbor refreshes the token automatically, so there is nothing to rotate by hand.
On a self-managed instance, your GitLab administrator can register an OAuth application for MergeHarbor with the api scope and the redirect URL shown in the console, or you can enter an existing application’s ID and secret when you connect.
Connect with an access token
If you would rather not tie the connection to a person’s account, use a group access token or a project access token:
- Role: Developer or higher.
- Scope:
api.
A group token covers every project in the group. Choose Connect with a token in the console and paste it; MergeHarbor verifies the token before storing it.
Why the api scope
The api scope looks broad, so it is worth knowing why it is needed. MergeHarbor reads projects, merge requests and code, posts merge request discussions and commit statuses, registers project webhooks and reads group members. GitLab has no narrower scope that allows posting merge request comments or commit statuses: read_api is read-only, and write_repository covers only Git pushes.
The token can still do only what its user or token role allows. That is why the docs recommend an access token with the Developer role rather than an administrator’s token. The full breakdown is on Code host permissions, along with how to revoke access.
Step 2: choose projects
Select the projects MergeHarbor should review. New repositories are enabled automatically unless an administrator turns off Auto-enable new repositories, so decide early whether you want every new project reviewed or only the ones you pick.
A sensible first rollout is a handful of active projects whose owners will give feedback. You can enable more later from Repositories.
A project belongs to one MergeHarbor organization at a time. If another organization has already connected it, enabling it is refused until it is disconnected there.
Step 3: webhooks and indexing
For each enabled project, MergeHarbor registers a webhook for three events: merge request, comments and push. You do not create webhooks by hand. Registering a project again, for example after a reconnect, replaces the webhooks MergeHarbor added before rather than adding duplicates.
In the background, MergeHarbor indexes each repository into a code graph, a text index and a semantic index. Progress shows in the Index column under Repositories: Queued, Indexing with a file count, then Indexed. Projects with recent activity are indexed first. After the first pass, only changed files are processed.
You do not have to wait for indexing. Reviews work straight away; until the index is built, the reviewer reads the files the merge request needs directly, and the summary notes when less codebase context was available. The quickstart explains every index status, including what Needs attention means.
Step 4: the first review
Open a merge request in an enabled project, or pick an open one under Review a pull request now in the console. On GitLab you will see:
- Discussions positioned on the diff, one per finding, each with a severity, a category, a confidence and a suggested fix where one applies.
- A summary note with an overview of the change and a confidence score from 1 to 5.
- A commit status that you can require before merging.
- Progress reactions: an eyes reaction when the review starts, thumbs up when it is posted, and a confused face if it fails. Turn them off with
reactions: { enabled: false }if your team finds them distracting.
Occasionally GitLab cannot position a comment on the diff, for example when the line is outside what GitLab shows. Those comments are not dropped; they are listed in the summary note.
By default MergeHarbor reviews again on new pushes, and after the first review only the new commits are reviewed. Earlier findings carry forward.
Step 5: commands in merge requests
You can talk to MergeHarbor in merge request comments:
| Comment | Effect |
|---|---|
@mergeharbor review |
Review the merge request again at its current head |
@mergeharbor review deep |
Review it at a higher tier this once (standard, deep or max) |
@mergeharbor remember <rule> |
Add a rule for this repository |
@mergeharbor test |
Start a proof run |
On GitLab you can leave out the @: a comment or line that starts with mergeharbor review works too. Questions still need the @mergeharbor mention. The full list is in Configure reviews.
Step 6: a starter configuration
Settings live in the console (organization defaults, then repository overrides) and in a .mergeharbor.yml at the repository root. The file is read from the merge request’s merge base, so a merge request cannot change how it is reviewed; edits take effect after they merge.
A conservative starting point:
# .mergeharbor.yml
version: 1
review:
trigger: pushes # opened, plus every new commit
review_drafts: false
strictness: medium
min_severity: minor
max_comments: 25
ignore_paths: ["gen/**", "**/*.pb.go"]
instructions: |
Every database query must filter by org_id.
filters:
- conditions:
- { field: author, op: exclude, values: ["renovate[bot]"] }
tier: standard
tier_rules:
- name: Release branches
conditions: [{ field: base_branch, op: include, values: ["release/*"] }]
tier: deep
merge_gate:
enabled: true
mode: advisoryEvery key here is in the configuration reference. A few notes:
instructionsis for conventions the reviewer cannot infer. Keep them short and concrete.- Deep reviews are on the Team plan and above, Max on Advanced and above. Auto picks among the tiers your plan includes; see Review tiers.
- Problems in the file never block a review. An invalid key is skipped and listed, with file and line, in the Configuration check section of the summary.
MergeHarbor also reads CLAUDE.md, AGENTS.md and similar agent instruction files from the merge base as team guidance, so conventions you already wrote for coding agents carry over.
Step 7: connect GitLab CI
When a pipeline fails on a merge request’s head commit, MergeHarbor can read the end of the failed job’s log and tie the failure to the changed lines it names. GitLab CI uses your existing GitLab connection, on GitLab.com or Self-Managed, so there is nothing to paste:
- In the console, open Integrations and choose Turn on on GitLab CI (under CI & builds).
- Choose Test connection, which lists the pipelines of one of your projects.
The connection’s api scope already allows reading pipelines and job logs; an access token needs at least read_api. CI is read only when a review runs or someone asks about it, and text that looks like a secret is redacted first. Details are in CI and builds.
Step 8: add the merge gate
The review tells you what is wrong. The merge gate tells you whether the merge request is safe to merge, combining open findings, review confidence, linked-issue requirements, tests, change risk and approvals into one verdict with a checklist. It is part of the Team plan and above.
On GitLab, the gate posts its own commit status named MergeHarbor / merge gate, next to the review status, which it never changes. To make it stop merges:
- On GitLab Ultimate, add an external status check whose name contains “MergeHarbor” under Settings → Merge requests → Status checks. MergeHarbor answers it as passed or failed for each commit.
- Switch the gate from advisory (the default, which reports without failing) to enforce once your team trusts the verdict.
The guide to merge gates covers presets, branch policies and a rollout plan.
How MergeHarbor learns on GitLab
GitLab gives MergeHarbor more feedback signals than most hosts. It learns from:
- Award emoji (thumbs up and down) on its comments.
- Fixes: a comment whose lines changed before merge counts as acted on.
- Replies in its threads. A reply that explains context (“we do this on purpose because…”) becomes a proposed rule for an admin to approve.
- Your reviewers’ own comments. Points your team keeps raising across merge requests become proposed rules.
Replies and teammates’ comments are read on GitHub and GitLab only. Nothing learned applies on its own: proposed rules wait under Memory → Custom rules for approval. See Learning and review quality, and how to reduce false positives for what to do in the first few weeks.
Private networks and self-hosting
MergeHarbor Cloud must be able to reach your GitLab instance, and GitLab must be able to deliver webhooks to MergeHarbor. Instances that are not reachable from the internet need a self-hosted MergeHarbor deployment inside your network, on Kubernetes with Helm or a single VM with Docker Compose, including air-gapped networks with models you serve yourself. See self-hosted AI code review for the overview.
Reconnect, switch accounts or disconnect
- Reconnect (Integrations → Code hosts) replaces the token of the account the connection belongs to, for example after a token expired or was revoked. Signing in as a different GitLab account is refused. After a reconnect, MergeHarbor registers the webhooks again; a project the account can no longer access stops being reviewed and shows a webhook error on the Repositories page.
- Switch accounts by disconnecting and connecting the other account.
- Disconnect stops reviews at once and removes MergeHarbor’s webhooks from GitLab. Reviews, index and settings are kept for 7 days, then permanently deleted. Reconnecting within those 7 days brings the projects back with their history.
GitLab sends no uninstall event, so revoking MergeHarbor’s token in GitLab alone stops reviews but deletes nothing. Remove the connection in the console as well.
Troubleshooting
No review appears on a merge request. Check that the project is enabled under Repositories and that its webhook has no error. Check your filters: a merge request from an excluded author, or drafts with review_drafts: false, is skipped by design. Bot merge requests (Renovate and others) are skipped by default. Comment @mergeharbor review to force a review.
A project shows a webhook error after a reconnect. The connected account or token can no longer access that project. Grant access or connect with a token that can.
Indexing shows Needs attention. The status says what stopped indexing and what to do, for example reconnecting the code host. Re-index once it is fixed. Reviews keep running in the meantime.
A change to .mergeharbor.yml had no effect. The file is read from the merge base, so the change applies to merge requests opened after it merges. Repositories → Configuration files shows the effective value of any setting and where it came from.
A comment is missing from the diff. If GitLab could not position it, it is in the summary note.
Enabling a project is refused. Another MergeHarbor organization has it connected. Disconnect it there first.
Start reviewing merge requests
Connect GitLab and the next merge request gets a review. Start a 14-day trial of the Team plan, with no card needed, and add the merge gate in advisory mode on day one so you can see its verdicts before you rely on them.