> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitLab Integration

> Configure GitLab access tokens, repository permissions, webhooks, and pipelines for ZeroPath scans

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](https://docs.gitlab.com/security/tokens/access_token_scopes/).

| Capability on the project | Reporter | Developer | Maintainer |
| - | - | - | - |
| Read code and run full repository scans | Yes | Yes | Yes |
| Post merge request comments | Yes | Yes | Yes |
| Create or update commit statuses | No | Yes | Yes |
| Configure project webhooks automatically | No | No | Yes |

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](https://docs.gitlab.com/user/permissions/).

> [!NOTE]
>
> **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](#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](https://docs.gitlab.com/user/project/integrations/webhooks/).

## Choose a token and limit access

| Credential | Use it for | ZeroPath setup option |
| - | - | - |
| Project access token | One approved project | **Project**, with its full path, such as `team/service` |
| Group access token | Projects in a dedicated group or subgroup, including descendants | **Group**, with its full path, such as `team/approved` |
| PAT from a dedicated account | Approved projects across groups; grant the account access only where needed | **Personal Access Token**, with no group or project path |

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](https://docs.gitlab.com/user/group/settings/group_access_tokens/) and
[project token](https://docs.gitlab.com/user/project/settings/project_access_tokens/) 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.

> [!NOTE]
>
> 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](https://docs.gitlab.com/user/group/settings/group_access_tokens/) and
> [project token](https://docs.gitlab.com/user/project/settings/project_access_tokens/) 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](https://zeropath.com/app/repositories?m=AddRepos).

**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](#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](/docs/scanning/pr-scanning.md#gitlab).

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

| Setting | Value |
| - | - |
| **URL** | The URL supplied by your ZeroPath deployment. The standard cloud URL is `https://zeropath.com/api/gitlab/webhook`. |
| **Secret token** | The exact webhook secret supplied by ZeroPath for this repository, separate from the GitLab access token. |
| **Triggers** | **Merge request events**, **Push events**, **Comments** (note events), and **Pipeline events**. |
| **Enable SSL verification** | Keep enabled; GitLab must trust the certificate served by ZeroPath. |
| **Custom webhook template** | Leave unset so GitLab sends its standard payload. |

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.

> [!NOTE]
>
> 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:

| Direction | Required access |
| - | - |
| **ZeroPath → GitLab** | HTTPS access to the GitLab API and Git repository endpoints, normally TCP 443 or the configured HTTPS port. |
| **GitLab → ZeroPath** | HTTPS POST delivery to the webhook URL supplied by ZeroPath. GitLab Rails and Sidekiq nodes must both be able to send webhooks. |

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](mailto:support@zeropath.com) 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](https://docs.gitlab.com/user/group/settings/group_access_tokens/#rotate-a-group-access-token)
and [project](https://docs.gitlab.com/user/project/settings/project_access_tokens/#rotate-a-project-access-token)
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.

| Symptom | What to check |
| - | - |
| A project is missing | Correct instance and full project/group path; token expiry; at least Reporter access to that project. |
| Cloning fails | Credential access, a branch with commits, DNS, network reachability, and TLS trust. |
| Webhook setup returns 403 | Project hooks need Maintainer or Owner. Group hooks need group Owner. Use project hooks to keep the integration at Maintainer. |
| An MR scan does not start | PR scanning is enabled, the MR is eligible under the scan settings, webhook delivery succeeds, and a suitable pipeline exists or can be created. |
| Commit status posting returns 403 | Developer or Maintainer access and compatible branch/pipeline rules. With Reporter, disable status posting and provide an existing pipeline. |
| Scans stop after token rotation | Update the existing ZeroPath connection with the replacement token and confirm it still reaches the intended projects. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.