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:

aura pr-review — run locally or in CI, post results as merge request notes or rich Code Quality reports.
.gitlab-ci.yml job — runs aura prove and aura pr-review as a pipeline gate.
Intent trailers — identical format to the GitHub integration.
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):

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`

[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:

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:

## 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:

[
  {
    "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

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:

[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:

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:

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:

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:

[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.