# GitLab Integration

*Self-hosted and gitlab.com, with first-class CI integration.*

## Overview

Aura supports GitLab as a peer to GitHub. Both the hosted `gitlab.com` and self-hosted GitLab CE/EE (14.0+) work. The integration surface is similar to GitHub's:

1. **`aura pr-review`** — run locally or in CI, post results as merge request notes or rich `Code Quality` reports.
2. **`.gitlab-ci.yml` job** — runs `aura prove` and `aura pr-review` as a pipeline gate.
3. **Intent trailers** — identical format to the [GitHub integration](/github-integration).
4. **Shadow branches** — pushed to GitLab the same way, under the `aura/` prefix.

The main differences from GitHub are: the token scope system, the Code Quality artifact format (GitLab has native merge-request UI for it), and protected branches vs. push rules.

## Setup

### 1. Create a Project Access Token

In GitLab, go to **Settings → Access Tokens → Project Access Tokens** and create a token with scopes:

- `api` (post MR notes, read pipelines)
- `write_repository` (push shadow branches)

Name it `AURA_TOKEN` and copy the value. Store it in **CI/CD → Variables** as `AURA_TOKEN`, masked and protected.

For self-hosted GitLab, use the same token mechanism — no feature-level differences.

### 2. Add the CI job

Create `.gitlab-ci.yml` (or extend an existing one):

```yaml
stages:
  - review

aura:
  stage: review
  image: ghcr.io/naridon-inc/aura:latest
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    GIT_DEPTH: 0  # full history needed for semantic diff
  before_script:
    - git fetch origin '+refs/heads/aura/*:refs/remotes/origin/aura/*'
  script:
    - aura prove --base origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME
    - aura pr-review
        --base origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME
        --format gitlab-codequality
        --output gl-code-quality.json
    - aura pr-review
        --base origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME
        --format gitlab-note
        --post
  artifacts:
    reports:
      codequality: gl-code-quality.json
```

The `codequality` artifact slot is GitLab-native: findings appear in the MR UI inline with affected files, with no extra app or webhook.

### 3. Require the job for merges

**Settings → Merge Requests → Merge checks → Pipelines must succeed.** Pair with **Protected Branches** on `main` to ensure the `aura` job is always present.

## Configuration

### `.aura/gitlab.toml`

```toml
[pr_review]
fail_on = ["error", "warning"]
post_single_note = true        # one collapsible note vs. many inline comments
collapse_unchanged = true

[codequality]
# Map Aura severity to GitLab severity.
map_error = "blocker"
map_warning = "major"
map_info = "minor"

[shadow_branches]
auto_push = true
prefix = "aura/"

[self_hosted]
# Only required for self-hosted GitLab.
base_url = "https://gitlab.internal.example.com"
ca_cert = "/etc/ssl/certs/internal-ca.pem"
```

### Environment variables in CI

| Variable | Purpose |
|----------|---------|
| `AURA_TOKEN` | Project access token. |
| `CI_SERVER_URL` | Auto-set by GitLab; Aura uses it for self-hosted URLs. |
| `CI_PROJECT_PATH` | Auto-set; used for MR note posting. |
| `CI_MERGE_REQUEST_IID` | Auto-set; identifies the MR. |

## Examples

### Self-hosted with a private CA

If your GitLab runs behind a private certificate authority, mount the CA into the runner:

```yaml
aura:
  image: ghcr.io/naridon-inc/aura:latest
  variables:
    AURA_CA_BUNDLE: /etc/ssl/certs/internal-ca.pem
    SSL_CERT_FILE: /etc/ssl/certs/internal-ca.pem
  before_script:
    - cp "$INTERNAL_CA" /etc/ssl/certs/internal-ca.pem
    - update-ca-certificates
  script:
    - aura prove --base origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME
```

Aura's HTTP client honors `SSL_CERT_FILE` and `AURA_CA_BUNDLE` for TLS trust.

### Posting a rich MR note

The `gitlab-note` format posts a single, collapsible note scoped to the MR. A sample payload:

```markdown
## Aura Semantic Review

**Summary:** 4 nodes modified, 1 added, 0 deleted.

### Intent mismatches (1)
- `auth::login` — stated intent: "add OAuth"; detected: "added OAuth + removed session timeout check"

### Architectural drift (0)
No layer violations found.

### Security findings (1)
- `db::exec_query` — string-concatenated SQL. See line 42.

_Generated by aura pr-review at abc1234 (base origin/main)._
```

### Using GitLab Code Quality reports

When you pass `--format gitlab-codequality`, Aura emits a JSON file matching GitLab's Code Quality schema:

```json
[
  {
    "description": "Intent mismatch: stated 'add OAuth', detected additional removal of session timeout",
    "severity": "blocker",
    "fingerprint": "a1f2e9...",
    "location": {
      "path": "src/auth/login.rs",
      "lines": { "begin": 42 }
    }
  }
]
```

GitLab deduplicates findings across pipelines via the `fingerprint` — Aura computes it from the violating AST node's stable ID so it survives line-number churn.

### Pushing shadow branches

```bash
aura shadow push origin
```

If your GitLab has push rules that forbid non-main-branch pushes, add an exception for `aura/*` via **Settings → Repository → Push Rules → Branch name**. Alternatively, configure Aura to push shadow branches to a separate mirror repo:

```toml
[shadow_branches]
remote = "aura-mirror"
```

## GitLab vs. GitHub: key differences

| Aspect | GitHub | GitLab |
|--------|--------|--------|
| PR review surface | Check runs + inline comments | Code Quality artifact + MR notes |
| Required-check enforcement | Branch protection | Protected branches + merge checks |
| Token type | `GITHUB_TOKEN` (auto) | Project Access Token (manual) |
| App model | GitHub App available | Webhook / CI-only |
| Self-hosted support | Enterprise Server only | Any GitLab CE/EE |
| Squash-merge trailer handling | Automatic via App | Requires `aura rewrite-trailers` step |

## Troubleshooting

**`aura: permission denied` when pushing shadow branches.** The Project Access Token lacks `write_repository`. Rotate the token with the correct scopes.

**Code Quality report not showing in MR.** The artifact `reports: codequality` slot only accepts one file. If another job also produces a Code Quality report, merge them or move Aura into a separate job that overrides.

**`aura prove` fails on the first MR after installing.** No shadow branches exist yet on origin. Push them once from a developer machine: `aura shadow push origin`.

**Self-hosted GitLab returns 401.** Aura defaults to `gitlab.com`. Set `base_url` in `.aura/gitlab.toml` or export `AURA_GITLAB_URL`.

**Pipeline runs on every commit but you only want MRs.** The `rules:` block above gates on `$CI_PIPELINE_SOURCE == "merge_request_event"`. If you also want to run on main, add a second rule for `$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH`.

## Review Apps and Preview Environments

If your team uses GitLab Review Apps, Aura can attach the `aura pr-review` report to the Review App's metadata page. Add:

```yaml
aura:
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_COMMIT_REF_SLUG.review.example.com
  artifacts:
    paths: [review.md]
```

Reviewers browsing Review Apps see the Aura report in the same place as the deployed preview URL — valuable context when manually exercising a feature.

## Review Note Anatomy

Aura's MR notes include:

- A summary table: nodes changed, added, deleted, intent match rate.
- Per-finding blocks with severity, file, line, reasoning, and suggested fix.
- Links back to the Aura dashboard for drill-down.
- A collapsible `<details>` block with the full AST diff for reviewers who want the raw view.

The note is posted once and edited in place on subsequent runs — avoiding the common GitLab anti-pattern of 20 stale bot comments on every MR. The edit is keyed on a hidden HTML comment containing the PR's fingerprint, so manual edits by reviewers are preserved.

## Scheduled Pipelines

Run Aura on a nightly schedule to catch drift on main even between MRs. This is valuable for detecting newly-introduced impacts as other branches merge:

```yaml
aura-nightly:
  stage: review
  image: ghcr.io/naridon-inc/aura:latest
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
  script:
    - aura prove --base origin/main~20..origin/main
    - aura pr-review --base origin/main~20 --format gitlab-note --post
```

Configure the schedule in **CI/CD → Schedules**. A nightly report over the last 20 commits gives you a rolling health view.

## GitLab Groups and Subgroups

For multi-project groups, provision a group-level access token rather than per-project. Aura will auto-discover all projects the token can reach:

```bash
aura integration enable gitlab --group acme --token "$AURA_GROUP_TOKEN"
```

Group-level reporting becomes possible: `aura report --group acme --last 30d` shows intent volume, Prove-failure rate, and impact count across every project in the group.

## Merge Request Approvals Integration

GitLab's merge-request approval rules integrate with Aura if you configure an external approval rule that gates on the `aura` job status. In **Settings → Merge Requests → Approval Rules**, add:

- Rule name: `Aura Semantic Gate`
- Required approvals: `1`
- Eligible approvers: a dedicated service account the Aura webhook can act as.

Combined with a webhook that approves when `aura prove` passes, this raises semantic correctness to a first-class approval on par with human review. A sample approval webhook is part of the `aura-gitlab` plugin.

## Using Merge Trains

GitLab's merge train reorders merges and re-runs pipelines per train commit. Aura behaves identically to how it does with GitHub's merge queue: shadow branches lag by one commit, intent trailers survive rebase-style trains, and `aura prove` re-runs on the train commit. The only gotcha is that long trains multiply `aura prove` CPU cost — enable `.aura/index` caching or a pre-warmed runner image to mitigate.

## Auditing With GitLab's Audit Events API

Aura's intent log can be mirrored to GitLab's own Audit Events API for SOC 2 / ISO 27001 trails. Enable:

```toml
[gitlab.audit]
enabled = true
events = ["intent.logged", "prove.failed", "zone.blocked"]
```

Each configured event becomes a GitLab audit event with full actor, branch, and intent metadata. Your compliance team can then produce reports from a single source (GitLab) without needing access to Aura directly.

## See Also

- [GitHub integration](/github-integration) — the GitHub counterpart.
- [CI/CD integration](/ci-cd-integration) — generic CI patterns.
- [MCP server](/mcp-server) — if your GitLab environment also hosts AI agents.
- [Custom plugins](/custom-plugins) — write a plugin to post to your internal code-review tool.