Connect your code
GitLab
Connect a GitLab group, on gitlab.com or a self-managed GitLab, with an access token and a group webhook.
GitLab has no app installation, so a GitLab group is connected with an access token you create and a group webhook you add. Merge requests are then reviewed like pull requests: a commit status, a summary comment, inline comments, reply commands, suggested changes and fix merge requests.
#What you need first
- To be an owner of the Nullgap organisation, signed in to the console. If your account has multi-factor sign-in, you are asked for a fresh code. An API key cannot connect a code host.
- On GitLab, permission to create a group access token and a group webhook on the top-level group.
- For a self-managed GitLab: a public https address. A private, loopback or internal address is refused with
private_address.
#Step 1: create the access token
In the GitLab group, create a group access token (a service-account token also works) with:
| Setting | Value | Why |
|---|---|---|
| Scope | api | Read merge requests and their diffs, post comments and commit statuses, fetch the code, and push a fix branch. |
| Role | Developer or higher | Developer is the lowest role that can set commit statuses and push branches. |
Nullgap lists the projects the token is a member of with at least the Developer role. Projects with merge requests switched off are left out.
#Step 2: connect the group
Open Integrations. Under Source code, in the GitLab row, press Connect a group and fill in:
| Field | What to enter |
|---|---|
| Group path | The group's path as it appears in its address, for example acme or acme/platform. The top-level group is what gets connected, with everything under it the token reaches. |
| Access token | The token from step 1. It is stored encrypted and never shown again. |
| GitLab address (self-managed only) | Leave empty for gitlab.com. For your own GitLab, its public https address, for example https://gitlab.acme.example. |
Before anything is stored, Nullgap checks that the token works and reaches that group. If it does not, you get gitlab_rejected: check the api scope and the Developer role.
#Step 3: add the group webhook
When the group is connected, the console shows a Webhook URL and a Secret token.
In GitLab:
- Open the group you connected, then Settings, Webhooks, Add new webhook.
- Paste the URL into URL and the secret into Secret token.
- Under Trigger, tick Merge request events and Comments. Tick Project events as well if you want new projects to appear in Nullgap on their own.
- Leave Enable SSL verification on, then save.
| Trigger | What it is for |
|---|---|
| Merge request events | Starting a review when a merge request opens, reopens or gets new commits. |
| Comments | Reply commands on findings, and the @nullgap review comment. |
| Project events | Reading the project list again when a project is added to or removed from the group. Without it, press Sync on Repositories. |
The webhook URL belongs to this one connection. GitLab sends the secret with every delivery, and a delivery with the wrong secret, or to an address that does not exist, is answered 401.
#What you will see
The group appears in Integrations as GitLab group on followed by the host, and its projects appear under Repositories with review switched on.
How GitLab differs from GitHub:
- The result is a commit status, named Nullgap Security Review, not a check with three outcomes. A failing review sets it to failed. A neutral result is written as success with a description that starts with "Neutral, not a pass:", because GitLab's other finished states would block merging. The icon is still green. See checks and gating.
- Drafts. A merge request is treated as a draft when GitLab marks it so, or when its title starts with
Draft:,[Draft],(Draft),WIP:or[WIP]. Drafts are not reviewed unless you ask. - Edits without commits do not start a review. Changing a title or a label, including removing the draft marker, sends no new commits. Push a commit or comment
@nullgap review. - Merge requests from forks. They are reviewed, but GitLab may refuse the commit status because the commit is on no branch of the project. The comments are still posted.
- Suggested changes use GitLab's own suggestion blocks, which the author applies with one click.
#Rotating the webhook secret
In Integrations, press Rotate webhook secret on the group. A new secret is shown once, with the same URL. The old secret stops working at that moment, so deliveries are refused until you have pasted the new one into the webhook's Secret token in GitLab.
Connecting the same group again, for example with a new access token, also issues a new webhook secret.
#Replacing the access token
An access token expires. To replace it, press Connect a group again with the same group path and the new token. The connection keeps its repositories, reviews and webhook URL. Update the secret in GitLab with the new one you are shown.
#What can go wrong
| Message or code | Cause | What to do |
|---|---|---|
gitlab_rejected | The token is wrong or expired, lacks the api scope, or is not a member of any project in that group with the Developer role. | Create a new token with the right scope and role. |
private_address | The self-managed address is not public. | Use an address reachable from the internet over https. |
step_up_required | Your second-factor check is older than fifteen minutes. | Confirm with your authenticator code, then try again. |
| Merge requests are not reviewed | The webhook is missing, its secret does not match, or Merge request events is not ticked. | Check the webhook's recent events in GitLab. |
| Reply commands do nothing | Comments is not ticked on the webhook. | Tick it and save. |
| Reviews and pentests fail after a while | The access token expired. | Replace it as described above. |
#Removing
Press Disconnect on the group. The stored token and secret are deleted, reviews stop and the projects leave the list. Past reviews and findings are kept. Delete the webhook and revoke the token in GitLab.
Nullgap documentation