GitLab

Connect GitLab from Settings > Integrations to let SubImage sync gitlab.com groups, projects, branches, dependencies, and vulnerability remediation metadata without a long-lived personal access token.

What SubImage Does

SubImage uses the GitLab OAuth integration as the default credential for the GitLab REST API when the GitLab sync module does not have a gitlab_token configured. The integration supports gitlab.com and gives SubImage short-lived tokens that refresh automatically.

The GitLab module still controls what SubImage ingests. After installing the integration, configure gitlab_root_groups in the GitLab module so SubImage knows which root groups to sync.

SubImage does not use the OAuth integration for self-managed GitLab instances or for private GitLab Container Registry image pulls.

Consent Scopes

When you install GitLab, SubImage requests these GitLab OAuth scopes:

• read_api
• read_repository
• read_user
• read_registry

SubImage uses these scopes to read group, project, branch, dependency, user, and registry metadata needed for GitLab sync and vulnerability remediation.

SubImage Setup

1. Install GitLab from Settings > Integrations.
2. Find each root group ID you want SubImage to ingest. In GitLab, open the root group and go to Settings > General.
3. Open the GitLab sync module in SubImage and add those IDs to gitlab_root_groups.
4. Leave gitlab_token empty when you want SubImage to use the OAuth integration credential.
5. Save the module.

Per-group token_arn overrides take precedence over the module-level gitlab_token, and gitlab_token takes precedence over the OAuth integration. You can use that precedence when one group needs a separate credential.

Personal Access Token Fallback

Use a GitLab personal access token instead of OAuth when:

• you are connecting a self-managed GitLab instance
• you need per-root-group credential isolation through AWS Secrets Manager ARNs
• you scan images stored in a private GitLab Container Registry

For PAT-based setup details, see the GitLab module setup guide.

Container Registry Support

The OAuth integration covers GitLab REST API access. It does not cover private GitLab Container Registry pulls during image scanning. GitLab Container Registry uses a registry authentication flow that does not accept the OAuth access token SubImage receives from GitLab.

If you scan private images from registry.gitlab.com, configure gitlab_token or a per-group token_arn with read_registry scope in the GitLab module.

Troubleshooting

If SubImage cannot sync GitLab after installation, confirm gitlab_root_groups is set in the GitLab module and that the authorizing GitLab user has access to those groups.

If the GitLab token is rejected, reinstall GitLab from Settings > Integrations so GitLab issues a fresh OAuth grant.

If private GitLab Container Registry pulls fail during image scanning, configure a PAT with read_registry scope in the GitLab module.