Connect GitLab

GitLab connections use an explicit credential rather than a GitHub App installation. Setup records the GitLab host, access token, credential ownership, and Git author identity that write-capable improvements would use.

Choose the GitLab host

Use gitlab.com for GitLab Cloud. For Self-Managed GitLab, enter the exact reachable host approved by your organization, without substituting a similarly named instance. Guard derives the GitLab API endpoint from that host and uses it to validate the credential and list projects.

One token belongs to one GitLab host. Do not reuse a token created on GitLab Cloud for a self-hosted instance, or a token from an unrelated self-hosted instance.

Choose token access

The setup form identifies three relevant GitLab scopes:

Scope	Why Guard may need it
api	Discover projects and use the GitLab API.
read_repository	Clone or fetch repository content for audits and code review.
write_repository	Push a verified Autofix branch when that workflow is enabled.

Use the smallest access that supports the workflows you intend to enable. A read-only audit path does not require write access merely because an Autofix exists elsewhere in the product.

SSH keys can clone and fetch, but they cannot list GitLab projects or call the GitLab API. They are not a replacement for the token used by this setup flow.

Code review and project statistics can also depend on GitLab webhooks. Guard can configure them only when the credential has sufficient project authority, such as an Admin, Maintainer, or Owner role. Without that authority, repository audits can still operate in a read-only mode when the required read access is present.

Choose credential ownership

Choose Save as personal when only the current Guard user should see and use the token. Choose Attach to project when project members should be able to select repositories and manage the shared connection.

For ongoing automation, prefer a dedicated service account or another credential with an owner, expiry policy, and rotation process your team can maintain. Record a Git author name and email allowed by your GitLab rules; these identify commits created by approved improvement workflows and are not required to match the token owner’s display name.

Connect the repository

1. Open New project, or choose Add a repository in an existing project.
2. Select GitLab.
3. Choose an existing healthy connection or select Add GitLab token.
4. Enter a connection name, host, access token, Git author name, Git author email, and credential ownership.
5. Save the token and wait for Guard to validate the connection.
6. Select the required GitLab project from the repository list.
7. Complete project setup.

Nested group paths remain part of the repository identity. Select the exact project rather than shortening a subgroup path to an owner/repository pair.

Verify connection health

Guard can show several credential states:

• Connected — the token can list repositories.
• Expires soon — the token expires within seven days; rotate it before automation depends on it.
• Needs a new token — the token expired or was removed in GitLab.
• Needs access — the token does not have enough GitLab access.
• Check later — GitLab could not confirm the token at that moment.
• Not checked — validate the connection before selecting repositories.

Use Check connection after changing GitLab access. Use Update token to rotate the secret without rebuilding the project connection. A token that needs attention cannot be treated as a reliable basis for scheduled audits or provider writes.

Provider boundaries

GitHub and GitLab support the same product model, but their provider artifacts differ: pull requests become merge requests, and comments become notes where applicable. Some source-link or report behaviors may still be provider-specific. Treat a provider-aware workflow as evidence that Guard knows the repository provider, not as a guarantee that every external link is identical across GitLab Cloud and every self-hosted version.

See Provider and write matrix for the external-state boundary and Repository is unavailable when a working connection later loses access.