GitLab

Built. The engine reads GitLab projects and groups, on GitLab.com or your own instance, and GitLab connects from LightHouse.

Connect in LightHouse

You need the client_admin role. Go to Setup and admin → Connectors → GitLab and enter the instance (https://gitlab.com or your own, HTTPS on port 443, host only), and the projects or groups to read.

One-click approval

1. Choose Approve in GitLab. Your instance shows the LightHouse OAuth application’s approval screen (authorisation code with PKCE).
2. Approve. GitLab returns you to LightHouse, which checks the grant and shows the connection.

The approval is valid for 15 minutes. If Atlantic’s OAuth application is not yet registered for your LightHouse, the card says so and offers the token route.

Access token

1. Create a personal, group or project access token at User settings → Access tokens (gitlab.com/-/user_settings/personal_access_tokens on GitLab.com) with only the scopes below.
2. Paste it into the card and choose Connect.

LightHouse calls /api/v4/user and /api/v4/personal_access_tokens/self to read the token’s scopes and expiry. A token with any write scope is refused.

From a terminal Coming

lighthouse connect gitlab will open the same approval with a device code, or, with your explicit yes, reuse your glab sign-in. See The CLI.

Connect in code

Add a source card to your deployment’s catalogue, and give the engine the token from your own secret store as GITLAB_TOKEN:

- id: gitlab-platform
  purpose: Read the platform group's issues, merge requests, pipelines and docs.
  executor: python
  target: aal_engine.ingest.connector:run_card
  overseer: platform-lead@example.com
  budget_usd: 0
  effect: internal
  source:
    kind: gitlab
    groups: [example-org/platform]          # subgroups included, archived projects left out
    instance_url: https://gitlab.example.com
    label: standard
    requires:
      reads: [issues, merge requests, failed pipelines, Markdown and wiki pages]
      reason: the operations agents answer from the platform's own records

Setting	Default	Notes
projects, groups	(one is required)	Paths such as group/project
instance_url	https://gitlab.com	Your own instance
credential_env	GITLAB_TOKEN	"" reads public projects without a token
issues, merge_requests, docs, wikis, ci, comments	true	Turn off what you do not want read
doc_paths	all	Limit Markdown to these paths

See In code.

Scopes

Scope	Why
read_api	Issues, merge requests, notes, pipelines, the repository tree and files, wikis. The engine needs only this one
read_repository	Asked for by LightHouse’s approval and listed for tokens, for repository reads
read_user	Asked for by LightHouse’s approval, to identify the account that approved

The engine calls, all GET under <instance>/api/v4: /groups/{g}/projects; /projects/{p}/issues and /merge_requests with their notes; /projects/{p}/pipelines, and the jobs of failed or cancelled ones; /projects/{p}/repository/tree and /repository/files/{path}/raw; /projects/{p}/wikis.

Where the credential is held

• For your deployment: in your own secret store, passed to the engine as GITLAB_TOKEN. Rotate it there.
• For the LightHouse connection: sealed under your tenant’s own key, never shown again, with its expiry tracked and a warning 14 days before it lapses.

What is indexed

Item	What is kept
Issues	Title, description and comments (system notes left out), state and labels
Merge requests	The same, with source and target branch
Pipelines	Status and ref; the jobs of failed or cancelled pipelines
Markdown files	Each .md file on the default branch, optionally under doc_paths
Wiki pages	Each page’s content

Never read: code and other non-Markdown files.

How often: on the card’s schedule. Each pull reads what was updated since the last; files and wiki pages are rewritten only when their content changes, and removed from the corpus when deleted at GitLab.

Check it worked

• The source’s run note: written N, unchanged N, quarantined N, removed N.
• The GitLab card in LightHouse: reads, items written and failures over the last 7 days.
• Agents → Knowledge: documents from gitlab.

Removing the connection

• In LightHouse: Disconnect (DELETE /api/v1/connections/{cid}). LightHouse revokes the OAuth grant at your instance where it can, clears the sealed credential, and keeps the record for the audit trail.
• In your deployment: remove the card and the token. Documents already written stay in the corpus until you delete them.