Skip to content
AletheiaAletheiaAletheia docs

Connect GitLab

GitLab connections use a group access token rather than an app installation. You create the token in GitLab and give it to Aletheia.

Creating the connection

Section titled “Creating the connection”
  1. In GitLab, create a group access token on the group whose projects you want indexed. Grant it the read_api and read_repository scopes. Read scopes are sufficient — Aletheia never writes.
  2. In Aletheia, go to Administration → Integrations → Source control (/admin/integrations/source-control) and add a GitLab connection.
  3. Supply the group path, the token, and — for self-managed GitLab — your instance base URL.

The token is stored encrypted and is never shown back to you.

Self-managed instances

Section titled “Self-managed instances”

Set the base URL to your instance, for example https://gitlab.example.com. Leave it empty for gitlab.com.

The URL is validated before it is stored. A base URL that resolves somewhere Aletheia will not call is rejected with unsafe_base_url rather than being retried against an internal address.

What it reads

Section titled “What it reads”
  • The projects in the group and its subgroups, so you can choose which are in scope.
  • Repository contents for the selected projects, to find infrastructure-as-code roots.
  • Merge requests that touch infrastructure code.

Connecting the top of a group tree is therefore enough; you do not add each subgroup separately.

Choosing projects

Section titled “Choosing projects”

As with GitHub, connecting makes projects available and selection puts them in scope. Unselected projects are not read.

Webhooks

Section titled “Webhooks”

Aletheia verifies GitLab webhook deliveries before processing them, and ignores replays. Webhooks keep the connection current; a manual sync re-reads directly.

Token expiry

Section titled “Token expiry”

GitLab group access tokens expire. When one does, the connection reports an error and stops syncing until you supply a new token. Nothing already indexed is lost.

Where to go next

Section titled “Where to go next”