# GitLab

> Connect GitLab to LightHouse: the ways to connect, the read-only scopes, where the credential is held, and what is indexed.

**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](https://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](/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`:

```yaml
- 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](/build/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.

Source: https://docs.atlanticagenticlabs.com/connect/gitlab/