Skip to main content
Gecko connects to GitLab with a GitLab access token and your instance URL. Gecko validates the token, stores the instance URL for your team, and uses the token to list repositories, read project metadata, clone code for scans, post merge-request comments, and open fix merge requests.
Self-managed GitLab is usually network-restricted. If your GitLab group, instance, or network limits access by IP, allowlist Gecko’s three IP addresses (one scanner, two frontend) before you connect, otherwise token validation, repo sync, and clones will fail even with a valid token. See Network & IP allowlist.

​
Connect

1

Create a GitLab access token

In GitLab, create a personal, group, or service-account token on an account that can access the repositories you want Gecko to scan:
  • Name: Gecko Security
  • Expiration: 1 year, or your team’s standard rotation window
  • Role: Developer or higher on the target projects
  • Scope: api
GitLab requires an expiration date unless an administrator has changed that policy. See GitLab personal access tokens.
The api scope is required to post comments on merge requests. With a narrower scope, scans still run but MR comments fail with 403.
2

Add the token in Gecko

Go to Settings > GitLab and enter your instance URL and token. Use the base URL only. Do not include /api/v4.
Use https://gitlab.com as the instance URL. No IP allowlisting needed.
Gecko validates the token with GET {instance}/api/v4/user. For security, Gecko rejects instance URLs that aren’t HTTPS or that point at private or loopback addresses.
3

Select repositories

Gecko syncs the projects your token can access (GET /api/v4/projects?membership=true). Select the repositories you want Gecko to track.
4

Configure the webhook

Gecko shows a webhook URL and a secret token. In GitLab, go to Settings > Webhooks, paste the URL, put the secret in Secret token, and enable:
  • Merge request events
  • Push events
  • Vulnerability events
Gecko verifies the X-Gitlab-Token header on every webhook. See Webhooks.

​
Where Gecko runs

DeploymentInstance URLNotes
GitLab.comhttps://gitlab.comCloud; no IP allowlist needed.
Self-managedYour base URLReachable over HTTPS. Allowlist Gecko’s IP addresses if access is IP-restricted.
GitLab DedicatedYour tenant URLAdd Gecko’s IP addresses to the Switchboard IP allowlist.

​
Network and IP allowlist (self-managed)

Self-managed GitLab and GitLab Dedicated usually restrict access by IP. If yours does, allowlist Gecko’s three IP addresses (one scanner, two frontend) before you connect, or token validation, repo sync, and clones all fail even with a valid token. GitLab.com needs none of this.
1

Confirm prerequisites

Your instance must be reachable over HTTPS with a valid certificate, and you need access to wherever IP access is enforced (GitLab settings, Switchboard, or your firewall). Get Gecko’s current IP addresses from your Gecko account contact; the canonical list lives on Network & IP allowlist.
2

Add the addresses where GitLab enforces IP access

Settings > General > Permissions and group features > Restrict access by IP address. Enter each address in CIDR notation (for example, 203.0.113.5/32). See GitLab group access and permissions.
In Switchboard, open Configuration > IP allowlist and add each address. See GitLab Dedicated network security.
If a firewall, proxy, or load balancer sits in front of your instance, allow inbound HTTPS from the three addresses there. For the NLB-vs-ALB source-IP details, see Network & IP allowlist.
3

Verify

A populated repository list confirms the frontend addresses are allowed; a successful scan confirms the scanner address is allowed. Allow all three; a partial allowlist causes confusing, partial failures.

​
What Gecko uses the token for

  • Validate the connection: GET /api/v4/user
  • List projects: GET /api/v4/projects?membership=true
  • Read branches, languages, commits, and merge-request details
  • Clone repositories over HTTPS for scan workers
  • Post merge-request comments and open fix merge requests
Use a dedicated service account scoped only to the groups and projects Gecko should scan, and rotate the token on a schedule.

​
Export findings back to GitLab

Gecko can push findings into GitLab’s native Security Dashboard. See GitLab vulnerability export.

​
Troubleshooting

Confirm the token is active, has the api scope, and that Gecko’s IP addresses can reach your instance. See Network & IP allowlist.
Usually an IP restriction. A valid token still can’t help if the network blocks Gecko. Allowlist the IP addresses and retry the sync.
The token is missing the api scope. Recreate it with api and reconnect.