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 dedicated service account

Create a service account in GitLab for Gecko instead of using a personal account. Gecko writes back to GitLab — it posts merge-request comments and opens fix merge requests — and those actions are authored by whoever owns the token you provide. A service account makes that activity show up as “Gecko” in your commit history, notifications, and audit log instead of under an individual’s name, and it keeps the connection working when that person leaves or rotates their own credentials.On GitLab Premium and Ultimate, use the built-in Service accounts feature. On Free, create a standard account to act as the bot (for example, gecko-bot). Either way, add it to the groups or projects you want Gecko to scan with the Developer role or higher.
This mirrors how Gecko connects to GitHub, where the GitHub App acts under its own gecko[bot] identity automatically. GitLab has no equivalent app identity, so a service account is how you get the same clean separation between Gecko’s actions and your team’s.
2

Create an access token

On the service account, create an access token that can reach 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.
3

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.
4

Select repositories

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

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

​
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
Comments and fix MRs are authored by the GitLab account that owns the token, so connecting with a service account keeps Gecko’s activity clearly attributed to “Gecko” rather than to an individual.
Scope the service account to only the groups and projects Gecko should scan, and rotate its 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.