# GitLab > GitLab: what the collector reads, how to connect it, its permissions, its certification by Atlantic Agentic Labs and its security posture. Built, not certified Built and tested against recorded and synthetic responses (version 1.0.0, 10 November 2026). Not yet run against the vendor's sandbox or a client environment. Reads Markdown files, issues, merge requests, wiki pages and failed-pipeline results from the GitLab projects (or groups of projects) you name, on GitLab.com or your own instance, so engineering agents can answer from the design notes, the review history and the failing builds. ## At a glance | Collector | GitLab, version `1.0.0` | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | Reads | GitLab: GitLab REST API v4 (GitLab.com and self-managed) ([the vendor's documentation](https://docs.gitlab.com/ee/api/rest/)) | | Family | Engineering | | Kind | Code | | Ways to connect | Access token, OAuth approval | | Scopes | - Read: `read_api` | | Read only | Yes | | Vendor's API can move money | No | | Personal data | Content, Identity | | Hosts it may contact | `gitlab.com` | | Vendor API versions | GitLab REST API v4 | | Lowest engine version | `0.45.0` | ## What it reads - Issues and merge requests: title, description and comments (system notes left out), state, labels, and for merge requests the source and target branches. Read since the newest `updated_at` seen per project. - Pipelines: status and ref; the jobs of failed or cancelled pipelines only. - Markdown files on the default branch, optionally only under `doc_paths`. The cursor keeps each file’s blob id; an unchanged file is not fetched, and one that leaves the tree is withdrawn. - Wiki pages: each page’s content; the cursor keeps a hash of it. A page that goes is withdrawn. - `groups` expand to their projects, subgroups included and archived ones left out. - Never read: code and other non-Markdown files. ## How to connect 1. Create a personal, group or project access token with the `read_api` scope only (User settings, Access tokens), or approve LightHouse’s OAuth application with the read level. 2. In LightHouse, open **Connectors**, choose **GitLab**, name the instance (GitLab.com by default), the projects (`group/name`) and groups, a label and how often to read, and approve or paste the token. 3. In code, give the deployment the token as `GITLAB_TOKEN` from your secret store and add a `kind: gitlab` source card with `projects` and/or `groups`, `label` and `requires`. Set `instance_url` for a self-managed instance. A source that sets `credential_env: ""` reads public projects without a token. ## Permissions `read_api` only. The collector sends only `GET` requests to `/api/v4`, with the token as a Bearer token; it never writes. The tree, file, wiki, issue, merge request, note and pipeline endpoints are all reads. Its read-only test proves it on every change. ## Limits - You must name projects or groups; a whole instance is never the default. Project paths are `group/name` (nested groups `a/b/name`). - The instance address must be `https://`; requests to any other host are refused. - Only pipelines that failed or were cancelled have their jobs listed. - A tree that GitLab pages is followed to its last page before anything is compared; a failing page fails the pull rather than withdrawing what was not listed. - A 304 with nothing cached is an error, never an empty listing. A wiki that answers 404 is left as it was, because GitLab answers 404 for a disabled wiki and for one the token cannot see alike. ## Data handling - Issue, comment, document and wiki text is copied into the deployment’s corpus under the source’s `label`. Notes carry the author’s name. Text can hold personal data. - The token stays in your secret store and is never written to logs or run notes; it is sent only to the instance host. - Nothing leaves the deployment: only counts reach LightHouse. ## Troubleshooting | What you see | What it means | What to do | | ---------------------------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------- | | `name the projects or groups to sync; a whole instance is never the default` | Neither `projects` nor `groups` is set | Name them | | `not group/name projects` | A project is not written `group/name` | Correct the path | | `instance_url must be an https URL` | The instance address is not https | Use the https address | | `credential variable 'GITLAB_TOKEN' is not set` | The token variable is empty | Set it, or `credential_env: ""` for public projects | | `HTTP 401` or `HTTP 403` | The token is revoked, expired or lacks `read_api` | Make a new token with `read_api` | | Read succeeded, 0 written | Nothing changed since the cursor | Nothing to do | ## Certification Each entry is a run by Atlantic Agentic Labs, newest first. Only a run against the vendor’s sandbox or a client environment certifies a collector; a certification lasts six months, or less if the vendor publishes an API version the collector does not list. See [How collectors are certified](/collectors/certification/). | Date | Collector | Engine | Vendor API | Method | Expires | | ---------------- | --------- | -------- | ------------------ | ----------------------------------- | -------------- | | 10 November 2026 | `1.0.0` | `0.45.0` | GitLab REST API v4 | Fixtures only: built, not certified | Not applicable | ## Security posture From the collector’s last scan on the default branch. What each line means, and what blocks a release: [Security posture](/collectors/security/). | Last scanned | 10 November 2026 | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Critical findings | 0 | | High findings | 0 | | Medium findings | 0 | | Low findings | 0 | | Info findings | 0 | | Release blocked | No | | Network allow-list check | Pass | | Read-only behavioural test | Pass | | SBOM (CycloneDX) | Produced | | Dependency licences | Pass | | Scanners | bandit 1.9.4, semgrep 1.181.1, pip-audit 2.10.1, osv-scanner 2.7.0, cyclonedx-py 7.5.0, pip-licenses 5.5.5, gitleaks repository job aal-secrets, hosts_check tools/hosts_check.py, read-only test pytest -m read_only | Source: https://docs.atlanticagenticlabs.com/collectors/catalogue/gitlab/