GitLab
Purpose
Maps groups, projects, branches, and dependencies from gitlab.com or self-hosted GitLab instances into Subimage. When combined with the scan module, Subimage can also scan images from GitLab Container Registry (GLCR).
For gitlab.com, the recommended way to connect GitLab is through the GitLab integration (Settings → Integrations). It uses a Subimage OAuth app with short-lived tokens that refresh automatically — no manual PAT rotation. See the GitLab integration guide for details. The PAT-based configuration below is the fallback for self-managed GitLab instances and is also required for GitLab Container Registry pulls (see Container Registry Support).
Secret fields below accept either an AWS Secrets Manager ARN or a value pasted directly into Subimage's managed vault. See Secrets for details.
Authentication Options
Option 1: OAuth Integration (preferred for gitlab.com)
Install the Subimage GitLab OAuth app from Settings → Integrations. Why this is preferred:
- Short-lived access tokens, refreshed automatically by Subimage
- No PAT rotation or expiry to track
- Least-privilege scopes requested:
read_api,read_repository,read_user,read_registry
You still configure gitlab_root_groups in the GitLab module; the OAuth integration only provides the credential. When no gitlab_token is set on the module, Subimage uses the OAuth credential for the GitLab REST API (sync and vulnerability remediation).
Self-managed GitLab is not yet supported through OAuth — use a PAT.
Option 2: Personal Access Token (PAT)
Use PAT-based configuration when:
- connecting a self-managed GitLab instance
- scanning images from a private GitLab Container Registry (GLCR pulls do not work with OAuth — see below)
- you need per-root-group credential isolation via AWS Secrets Manager ARNs
A PAT and the OAuth integration can coexist: per-group token_arn > module-level gitlab_token > OAuth integration credential.
Required Fields
| Field | Secret? | Description |
|---|---|---|
gitlab_token |
Yes | GitLab Personal Access Token |
gitlab_root_groups |
No | One or more root group IDs to ingest (find these in each group's settings page or URL) |
gitlab_url |
No | GitLab instance URL (default https://gitlab.com; set to your self-hosted URL, e.g. https://gitlab.example.com) |
gitlab_container_registry_host |
No | Container registry hostname for self-hosted GitLab (e.g. registry.gitlab.example.com). Leave empty for gitlab.com. |
tailscale_hostname |
No | Outpost hostname for a GitLab instance on a private network. See Connect GitLab on a private network. |
Token Scopes
Required:
read_api— groups, projects, branches, dependenciesread_repository— repository metadata and file contentsread_user— user profile for group / project membership
Optional (for GLCR scanning):
read_registry— pull container images from GitLab Container Registry
The token must have access to all root groups you want to sync. For self-hosted GitLab, this may require an admin or a user who is a member of every target group.
Project Access
The token's user or service account should have at least the Developer role on projects where you want dependency findings from GitLab dependency scanning. Subimage reads those findings from CI job artifacts, and GitLab can restrict artifact downloads with settings such as artifacts:access: developer. A Reporter-level token can still list projects, jobs, and artifact metadata, but receive 403 Forbidden when downloading dependency scanning artifacts.
The service account can be assigned the Developer role while the token remains limited to read-only scopes: read_api, read_repository, read_user, and optionally read_registry for GLCR scanning. GitLab evaluates both the token scopes and the account's project role, so this token can download Developer-restricted CI artifacts without granting write-capable token scopes. Do not grant broad scopes such as api, write_repository, or registry write scopes. If assigning Developer to the service account is not acceptable, configure dependency scanning artifacts so Reporter-level project members can download them.
Setup Steps
- Generate a Personal Access Token:
- User Settings → Access Tokens (or Group Settings → Access Tokens for group-level tokens)
- Select
read_api,read_repository, andread_user(addread_registryif you also want GLCR image scanning — see Token Scopes) - Set an expiration date and click Create personal access token. Copy the value.
- Find your group IDs. In each root group, go to Settings → General — the Group ID is shown at the top of the page.
- In Subimage, fill in:
gitlab_token— the token (or its AWS Secret ARN)gitlab_root_groups— one entry per root group IDgitlab_url— only for self-hosted GitLabgitlab_container_registry_host— only if your registry uses a custom hostname
- Save the module.
Connect GitLab on a private network
If your self-managed GitLab instance isn't reachable from the internet, connect it through a Subimage Outpost. The Outpost runs in your network next to GitLab and opens an outbound-only, encrypted Tailscale tunnel to Subimage. You don't need to open any inbound ports.
Deploy an Outpost for GitLab
Follow the Outpost guide, using Outpost 1.2.4 or later.
Set the following Outpost values:
Docker variable / Helm value Value PROXY_TARGET/outpost.proxyTargetYour GitLab URL without a path, for example https://gitlab.example.internalNAME/outpost.namegitlab, or any name that's unique in your deploymentVERIFY_TLS/outpost.verifyTlstrueCA_BUNDLE/outpost.caBundleThe path to your certificate authority (CA) certificate, if GitLab uses an internal CA In Settings → Outposts, confirm that
shows as Online.<TENANT_ID>-gitlab-outpost
The following Helm values file deploys an Outpost that reaches only GitLab:
outpost:
tenantId: "<TENANT_ID>"
name: "gitlab"
proxyTarget: "https://gitlab.example.internal"
verifyTls: true
# Required only if GitLab uses a certificate from an internal CA.
caBundle: "/etc/outpost/ca/ca.crt"
authKey:
value: "<outpost-registration-key>"
# This Outpost proxies GitLab, not the Kubernetes API, so it doesn't need cluster RBAC.
rbac:
create: false
extraVolumes:
- name: gitlab-ca
configMap:
name: gitlab-ca
extraVolumeMounts:
- name: gitlab-ca
mountPath: /etc/outpost/ca
readOnly: trueThe following command deploys the same Outpost with Docker:
docker run -d \
--name subimage-outpost-gitlab \
--restart unless-stopped \
-e TAILSCALE_AUTHKEY='<outpost-registration-key>?ephemeral=true' \
-e TENANT_ID=<TENANT_ID> \
-e NAME=gitlab \
-e PROXY_TARGET=https://gitlab.example.internal \
-e VERIFY_TLS=true \
-e CA_BUNDLE=/etc/ssl/gitlab-ca.crt \
-v /path/to/internal-ca.crt:/etc/ssl/gitlab-ca.crt:ro \
ghcr.io/subimagesec/subimage-outpost:${OUTPOST_VERSION}Point the GitLab module at the Outpost
- In Subimage, open the GitLab module.
- Set the following fields:
gitlab_url: the same URL asPROXY_TARGET, for examplehttps://gitlab.example.internal.tailscale_hostname:.<TENANT_ID>-gitlab-outpostgitlab_tokenandgitlab_root_groups: the values described in Setup Steps.
- Save the module.
Subimage sends every GitLab API call through the Outpost. Graph nodes keep your GitLab URLs, so links in Subimage open GitLab directly.
Container registry
An Outpost forwards traffic to a single target, so Subimage reaches GitLab's API through it but not a container registry that GitLab serves from its own host or port. Subimage connects to that registry directly. If the registry isn't reachable from the internet and projects in your synced groups store images in it, the sync for those groups fails when it reaches the registry. To avoid this, keep the container registry disabled on those projects.
The scan module and remediation merge requests connect to GitLab directly, not through the Outpost.
Troubleshooting
| Sync error | Cause and fix |
|---|---|
Outpost Unreachable |
Subimage can't reach the Outpost over Tailscale. Check that the Outpost container is running and that tailscale_hostname matches the name in Settings → Outposts. |
Outpost Cannot Reach Target |
The Outpost is running but can't connect to GitLab. The error names the target and the cause. Check that PROXY_TARGET resolves from the Outpost's network. For CERTIFICATE_VERIFY_FAILED, mount your internal CA and set CA_BUNDLE. |
401 Unauthorized or 403 Forbidden |
The token is invalid or lacks the required scopes. See Token Scopes. |
Multi-root-group Support
Each root group is synced sequentially with a shared cleanup tag. If one group fails, the others continue.
Use per-group token_arn overrides only when a group needs different credentials.
Container Registry Support
When both the gitlab and scan modules are configured, Subimage detects GLCR images during scan syncs and authenticates with your GitLab credentials.
GLCR pulls require a PAT. The OAuth integration does not cover container registry authentication — registry.gitlab.com uses a JWT exchange that does not reliably accept OAuth access tokens. If you scan images stored in a private GitLab Container Registry, configure gitlab_token (or per-group token_arn) with the read_registry scope, even when the OAuth integration is installed.
Registry host detection:
- gitlab.com →
registry.gitlab.com - self-hosted GitLab → derived from
gitlab_url(e.g.https://gitlab.example.com→registry.gitlab.example.com) - override with
gitlab_container_registry_hostwhen your registry uses a different hostname
What Gets Synced
- Organizations — top-level groups
- Groups — subgroups
- Projects — repositories and metadata
- Branches — branch info including protection status
- Dependencies — from GitLab dependency scanning artifacts and dependency manifest files (e.g.
requirements.txt,package.json,Gemfile) - Container Images — from GLCR (when scan is configured)