Connect GitLab
GitLab.com and self-managed instances, including ones on a private network behind their own certificate authority.
The full guide — the token types and what each one can reach, the
connections.yml shapes, self-managed setup, webhook registration, and
a failure-by-failure section — lives with the code it describes:
→ docs/CONNECT_GITLAB.md in archgraph-api
Kept there for the same reason as the on-premise runbook: every YAML example in it is parsed by the real loader in CI and the provider list is read from the capability registry, so a stale line fails a test rather than an install.
The short version
| Needs | Without it | |
|---|---|---|
| Clone private repositories | read_api | git clone fails |
| Push-triggered refresh | api scope and Maintainer | The poll refreshes instead — latency, not accuracy |
| Detect that upstream moved | read_api | Freshness fields stay unknown |
The scope that surprises people
read_api is the one that matters. It covers everything short of
registering a webhook, including git clone — which contradicts
GitLab's own documentation, and contradicted an earlier version of our
guide too.
read_repository alone does not work. It cannot even pass the
connection check ArchGraph runs at bring-up, so a connection declared
with it is refused before a clone is ever attempted.
Measured on GitLab CE 19.3 against a private project with a group access token at Reporter:
| Scopes | GET /api/v4/user | HEAD poll | git clone |
|---|---|---|---|
read_repository | 403 | 403 | works |
read_api | 200 | 200 | works |
| both | 200 | 200 | works |
If a clone fails, check the token's role and group membership first. Scopes are the last thing to suspect, not the first.
Self-managed instances
Supported, and tested against a real self-managed GitLab rather than assumed. Three things to know:
- A private hostname has to be named in
ARCHGRAPH_ALLOWED_GIT_HOSTS. The SSRF guard rejects every private address by default, which is correct and also fatal forgitlab.internaluntil you opt in. - An internal certificate authority is named with
ARCHGRAPH_EXTRA_CA_FILE, and ArchGraph merges it into the system trust store. SettingREQUESTS_CA_BUNDLEyourself replaces that store instead, and the install silently stops trusting github.com and the vulnerability database. - GitLab has its own outbound allow-list. A webhook pointing at a local
address is refused with
Invalid url givenuntil the instance admin permits it.
The runbook has the exact settings for all three.