Connecting GitLab
A GitLab connection is an access token plus a base URL — gitlab.com by default, or your own self-managed host. Each attached project then has its own toggles for what feeds the board and what syncs for intelligence.
Creating a GitLab connection against a self-managed instance.
| Field | Value |
|---|---|
| API base URL | Defaults to https://gitlab.com/api/v4; set your own host for self-managed GitLab |
| Access token | Personal or project token, sent as the PRIVATE-TOKEN header |
| Project | group/project, chosen from a live server-side search |
What it does, and where the data comes from
Whatever host you type in — with or without a trailing slash, with or without /api/v4 already on it — is normalized to the same canonical API base before Deckgauge stores it. This one normalization is shared by the connection form and the worker's own sync path, so both agree on the same URL; a prior version where they disagreed left instances 404ing against the web UI's stored host.
How to connect GitLab
- Create an access token with
read_api,read_repository, andread_userscopes. - Add source → GitLab — for self-managed GitLab, set the base URL to your instance; leave it default for gitlab.com.
- Paste the token and Create & test.
- Search and pick a project — your own projects match first; if none match, the search widens to every project the token can see.
What syncs
Per project: merge requests, issues, and reviews always sync into intelligence; commit sync is a separate toggle. On the board's Source zone, Sync issues and Sync merge requests are independent switches controlling what actually lands as board rows — leaving both off keeps the connection populated for intelligence without adding any rows to the board.
Under the hood
Project discovery is scoped intentionally: with no search term, you get your own projects (membership=true). With a search term, your own matching projects are tried first; only if that comes back empty does the search widen to every project the token can see. This keeps gitlab.com results from being buried under public projects across the whole platform, while still letting self-managed users with broad read access find projects they aren't formally a member of. Results are capped at 100 rows — narrow the search term to see more.
If it looks wrong
| Symptom | Cause | Fix |
|---|---|---|
| Connection test fails against a self-managed host | Base URL isn't the API root, or the instance uses a different path | Confirm the host resolves to <your-host>/api/v4 and retest |
| Project search returns nothing you expect | Token has no membership on that project, and the search term didn't widen to a public match | Try a more specific search term, or add project membership in GitLab |
| No commits show up for a project | Commit sync is off for that project | Enable commit sync on the project's connection settings |
Related
- Mapping source statuses — how GitLab's issue/MR states map onto board statuses.
- When your data refreshes — scheduled and manual sync.
- When a connection breaks — health checks and reconnecting.
Last updated