Skip to main content
ZeroPath connects to GitLab.com and GitLab Self-Managed with a project access token, group access token, or personal access token (PAT). The recommended setup is the api scope with Maintainer access to the projects you approve. ZeroPath does not require a GitLab administrator credential.

​
Requirements

  • A ZeroPath organization and permission to create integrations and add repositories.
  • A valid GitLab access token with the api scope and at least Reporter access to each repository you intend to scan. Set an expiry that follows your organization’s policy and GitLab’s limits; ZeroPath does not require a one-year lifetime.
  • An HTTPS GitLab hostname reachable from your ZeroPath deployment. For automatic MR scans, GitLab must also be able to deliver webhooks back to ZeroPath.
  • A branch with at least one commit before running a scan. Empty repositories can be imported, but need code before they can be scanned.

​
Permissions

Token scopes and GitLab roles are separate controls. The api scope permits API reads and writes within the credential’s access; it does not elevate the token’s project role. Use api for this integration rather than substituting read-only scopes for webhook or status writes. See GitLab’s token scope documentation. Comments require the corresponding ZeroPath review features to be enabled. Reporter access does not allow pushing fix branches. Protected branch and pipeline rules can further restrict status writes and remediation. Check permissions on every project, including when one token covers multiple projects. See GitLab’s roles and permissions.
Reporter is the minimum for repository scanning. For automatic MR scanning with a Reporter token, a project Maintainer or Owner must configure the webhook, an existing pipeline must be available for the scanned commit, and Check status posting must be disabled. Use Developer or Maintainer when GitLab commit statuses are needed. See Merge request pipelines.

​
Project and group webhooks

Maintainer is sufficient to manage project webhooks. Optional group webhooks require the group’s Owner role and an eligible GitLab plan. Project webhooks let the integration credential remain Maintainer. If group-level setup reports a permissions warning, verify project webhook delivery for each imported repository before relying on MR scans. See GitLab’s webhook requirements.

​
Choose a token and limit access

A customer-side group Owner creates a group access token; a project Maintainer or Owner creates a project access token. The token itself can be assigned a lower role. On GitLab.com, group and project tokens generally require Premium or Ultimate. On Self-Managed, they are available with any license. Organizational settings can further restrict token creation. See the group token and project token guides. To restrict the integration to a subset of repositories:
  • Use project tokens, or put the approved projects in a dedicated subgroup and grant access at that subgroup. Avoid broad parent-group membership for a dedicated account.
  • Account for inherited access. Group tokens cover descendant and future projects in the group; a PAT follows the account’s memberships.
  • Select only approved repositories when importing into ZeroPath, and review automatic import settings if enabled. The selection and the group/project path entered in ZeroPath do not reduce the GitLab permissions of a broader credential.
On GitLab instances using Internal visibility, group and project tokens created by an internal user can access other Internal projects. Review project visibility as well as token membership when a strict repository boundary is required. GitLab documents this behavior in its group token and project token guides.

​
Connect GitLab

1

Create the credential

For a group or project token, open the resource’s Settings → Access tokens in GitLab. For a dedicated account PAT, use that account’s personal access token settings. Set a name, expiry, api scope, and the role required for your workflow. Enter the credential directly into ZeroPath, or use your approved secure channel if another team performs setup.
2

Open the GitLab setup dialog

In your ZeroPath deployment, go to Add Repositories → GitLab → Setup GitLab Integration. For the standard cloud deployment, open Add Repositories.
3

Choose the token type and enter connection details

Select Group, Project, or Personal Access Token and paste the token.
  • GitLab Domain: gitlab.com or your instance hostname, such as gitlab.example.com. A configured HTTPS port can be included. Keep repository paths out of this field.
  • Group Name: for Group connections, the full group or subgroup path, such as engineering/approved, rather than its display name.
  • Project Path: for Project connections, the full project path, such as engineering/approved/service.
Personal Access Token connections do not require a group or project path.
4

Add repositories

Select the approved projects from Accessible repositories and add them. If ZeroPath reports that webhook setup could not be completed, follow Manual project webhook setup.
5

Enable scanning and verify

Enable PR scanning for MR reviews in the repository’s scanner settings. Enable Check status posting when the token has Developer or Maintainer access. Run a full scan and open or update a real MR to verify the workflows you intend to use.

​
Merge request pipelines

Automatic MR scans need a GitLab pipeline for the commit being scanned. ZeroPath looks for:
  1. An existing MR pipeline for that commit.
  2. An existing branch pipeline for that commit.
  3. An external pipeline created by posting a commit status, if Check status posting is enabled and the credential can write statuses.
If scanner settings require a CI pipeline (requireCiPipeline), an existing MR pipeline is required; branch and external pipelines are not used as fallbacks. If no suitable pipeline can be resolved or created, the automatic MR scan does not start. A Reporter token cannot create an external pipeline through the commit-status API. With Reporter access, arrange for an existing pipeline for each scanned commit and disable Check status posting. A manual webhook alone does not satisfy the pipeline requirement. Full repository scans do not require a GitLab pipeline. To block merges on scan results, use Developer or Maintainer access for status posting and configure GitLab’s merge checks. See GitLab merge checks.

​
Manual project webhook setup

When the integration has Maintainer access, ZeroPath can configure project webhooks during repository import. If automatic setup fails, or the credential has Reporter or Developer access, ask a project Maintainer or Owner to create the hook:
  1. Copy the URL and repository-specific secret from ZeroPath’s GitLab Webhook Setup Required dialog.
  2. In the GitLab project, open Settings → Webhooks → Add new webhook.
  3. Configure the following settings, then save the webhook.
These events match ZeroPath’s automatic project webhook configuration. Issues, wiki pages, tag pushes, and job events are not required. Repeat setup for each imported project that needs a manual hook.
If your GitLab version offers both Signing token and Secret token, keep the ZeroPath value in Secret token. The integration authenticates the X-Gitlab-Token header; configuring only a signing token does not replace that requirement.
Test delivery in GitLab and then open or update a real MR. Successful webhook delivery alone does not establish that a scan ran; confirm the scan and commit in ZeroPath.

​
Network and TLS

Self-managed GitLab connections need network access in both directions: DNS must resolve correctly and TLS certificates must be trusted in each direction. Use the GitLab instance’s HTTPS hostname, without a group/project path or an /api/v4 suffix. For private-only GitLab hosts, internal certificate authorities, or IP allowlists, coordinate network access and certificate trust with your deployment administrator or ZeroPath support before connecting. Private-address access depends on your ZeroPath deployment’s network policy. The GitLab setup dialog does not provide a CA bundle upload field; certificate trust must be configured for the deployment.

​
Replace or rotate a token

Before expiry, open a connected ZeroPath repository and select Settings → GitLab Installation Token → Update Token. Select the existing connection and provide the replacement token while preserving the intended GitLab instance and repository access. The update applies to all repositories using that connection and preserves scan history, findings, and repository settings. Where policy permits, create a replacement token, update ZeroPath, and verify access before revoking the old token. GitLab’s Rotate action invalidates the previous token immediately, so update ZeroPath promptly when using it. See GitLab’s group and project token rotation documentation. If the ZeroPath connection was already deleted, create a replacement with access to the same projects. When it syncs matching projects on the same GitLab instance, ZeroPath can reconnect the preserved repositories with their history and settings. Projects inaccessible to the new token, or hosted on a different instance, remain disconnected.

​
Validate and troubleshoot

Confirm that the imported repositories match your approved scope, a full scan completes, and a real MR update starts a scan for the latest commit. When status posting is enabled, verify ZeroPath Security Scan (or your deployment’s custom check name) appears on the pipeline GitLab evaluates for the MR. Comments depend on the enabled review settings and the scan’s findings.