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

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

Token Scopes

Required:

• read_api — groups, projects, branches, dependencies
• read_repository — repository metadata and file contents
• read_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

1. Generate a Personal Access Token:
   • User Settings → Access Tokens (or Group Settings → Access Tokens for group-level tokens)
   • Select read_api, read_repository, and read_user (add read_registry if you also want GLCR image scanning — see Token Scopes)
   • Set an expiration date and click Create personal access token. Copy the value.
2. Find your group IDs. In each root group, go to Settings → General — the Group ID is shown at the top of the page.
3. In SubImage, fill in:
   • gitlab_token — the token (or its AWS Secret ARN)
   • gitlab_root_groups — one entry per root group ID
   • gitlab_url — only for self-hosted GitLab
   • gitlab_container_registry_host — only if your registry uses a custom hostname
4. Save the module.

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.

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_host when 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)