# GitLab Integration — gitlab.com and Self-Managed

> Connect GitLab with a token (read_api, read_repository) to browse projects and branches and deploy from GitLab repos — self-managed instances included.

Source: https://zop.dev/integrations/gitlab
Updated: 2026-08-20

---

## Common questions

### What scopes does the GitLab token need?

read_api and read_repository, and nothing beyond them. zop.dev does not need write scope to list projects, clone code and deploy.

### Does self-managed GitLab work?

Yes. Supply your server URL and the same two scopes apply; the API path is handled for you. The connection is verified against the API on save, so a firewall rule or an expired certificate surfaces immediately rather than as a confusing build failure days later.

### Personal or group access token?

A group access token is usually better: it survives the person who created it leaving, and its reach is bounded to the group rather than to one individual's whole account. Personal tokens behave identically and are the faster path for a trial.

Point zop.dev at gitlab.com or your self-managed GitLab with a single token and deploy straight from your projects. Nested groups work out of the box, and the connection is verified live before it saves.

## read_api and read_repository, nested groups included

Uses the official GitLab API with a personal or group access token carrying read_api and read_repository scopes. For self-managed instances, provide your server URL; the API path is handled automatically. Project listing honors your membership, including nested subgroup paths.

## Create the token, paste it, pick your projects

1. In GitLab, create a personal or group access token with read_api and read_repository.
2. Settings > Integrations > GitLab; paste the token (and server URL for self-managed).
3. Pick projects and branches in the deploy flow.

## Projects, branches, clones and self-managed support

Project and branch listing, clone access for builds, self-managed GitLab support, nested group support.

## Personal or group token

A group access token is usually the better choice: it survives the person who created it leaving,
and its reach is bounded to the group rather than to an individual's full account. Personal
tokens work identically and are the faster path for a trial.

Both need `read_api` and `read_repository`. Nothing more: zop.dev does not need write scope to
build and deploy from a project.

## Self-managed instances

Point the connection at your own host and the same two scopes apply. The verification step calls
the API on save, so a firewall rule or an expired certificate surfaces immediately rather than
as a confusing build failure days later.