GitLab Integration

The GitLab integration uses OAuth. VULQN connects to a GitLab group, creates a webhook for merge request events, syncs repositories, and lets you choose which repositories should be reviewed.

Connect GitLab

1. Open Onboarding or Settings → Add provider in VULQN.
2. Choose Connect GitLab.
3. Authorize VULQN on GitLab. (Scopes needed: api, read_user.)
4. Select the group to monitor.
5. VULQN detects whether your group supports group-level webhooks (GitLab Premium) or falls back to project-level webhooks automatically.
6. Return to VULQN after the connection completes.

After setup, VULQN syncs repositories from the selected group. Enable only the repositories where reviews should run.

Webhook modes

VULQN uses one of two webhook modes depending on your GitLab plan:

Mode	GitLab plan	How it works
Group webhook	Premium	One webhook covers all repositories in the group automatically.
Project webhook	Free / any	A webhook is registered per repository when you enable it in Settings.

VULQN detects the correct mode automatically during connection. No configuration is needed.

Enable repositories

In Settings:

1. Find the GitLab connection.
2. Use Sync repos if the list is stale.
3. Enable the repositories VULQN should review.
4. Confirm the branch field. New repositories default to main,master.
5. Turn on peer review only for repositories that need it and have peer credits available.

For project-webhook mode, enabling a repository registers its webhook automatically.

GitLab events VULQN responds to

VULQN creates a webhook for:

• Merge request opened.
• Merge request updated.
• Merge request merged.
• Merge request closed.
• Note (comment) created on a merge request.

Those events allow VULQN to review new MRs, re-review updated MRs, process !vulqn commands, track comment-thread resolution, and update merged or closed review status.

Draft merge requests (title prefixed with Draft: or WIP:) are skipped by default unless trigger.skipDrafts is set to false in .vulqn.json.

OAuth access

VULQN requests api and read_user scopes during OAuth. The api scope covers reading diffs, posting inline comments, setting commit statuses, and managing webhooks. The read_user scope is used to retrieve the authorizing user’s email address.

GitLab access tokens expire and are refreshed automatically. If the token is revoked, VULQN marks the connection inactive and stops processing MRs until you reconnect.

Webhook repair

If a webhook is deleted or the secret becomes invalid, use Repair Webhook in the GitLab connection section in Settings. VULQN generates a fresh secret, recreates the hook, and resumes processing.

Troubleshooting

Problem	What to check
Group is not listed	Only groups where you have Maintainer access or above are shown.
Repositories are missing	Use Sync repos in the GitLab connection section.
MRs are not reviewed	Confirm the repository is active and the target branch matches the branch filter. Also check that the repository webhook is registered (project-webhook mode).
Connection was revoked	Reconnect GitLab from onboarding or settings.
Webhook not firing	Use Repair Webhook in the GitLab connection section.

For MR comment commands, see !vulqn Commands.