GitLab Integration

Connect GitLab.com or a self-hosted GitLab server to Brief so your agents know what's actually built from merge requests and issues.

Last updated: July 5, 2026

Brief reads merge requests and issues from your GitLab projects so agents and teammates can check what's actually shipped instead of guessing from Linear or docs. This page covers both GitLab.com and self-hosted GitLab servers — pick the section that matches your setup.

What does Brief capture from GitLab?

  • Projects — the repos Brief has visibility into
  • Merge Requests — open, merged, and closed MRs
  • Issues — optional; a single toggle turns issue mining on or off across the projects you select
  • User info — who's authoring the work

Brief has read-only access — it never opens, comments on, or merges anything in GitLab.

Why connect GitLab to Brief?

Ground truth for agents

Agents checking "does this already exist" get a real answer from merge request activity instead of inventing duplicate work.

One connection for the whole org

GitLab is a team-level integration — an admin connects it once and every project you select is visible to the whole org. Teammates don't each need to authorize their own account.

Works with your own GitLab server

If your team runs GitLab on its own infrastructure rather than gitlab.com, Brief connects to that instance directly, including self-signed certificates.

How do I set up the GitLab integration?

GitLab.com

Setup time: 2 minutes
Initial sync: 1-2 minutes
Updates: Real-time via webhooks
  1. Go to Integrations in Brief
  2. Find GitLab and click Connect
  3. Authorize Brief in GitLab's OAuth flow
  4. Select projects — pick which projects Brief should analyze, then toggle whether to include issue mining across the projects you selected
  5. Click Complete Setup
  6. Done! Brief starts syncing merge requests (and issues, if selected)

Self-Hosted GitLab

Setup time: 3-5 minutes
Initial sync: 1-2 minutes
Updates: Periodic sync (no webhooks on self-hosted)
  1. Go to Integrations in Brief
  2. Find GitLab (Self-Hosted) and click Connect
  3. Enter your instance URL — for example https://gitlab.example.com
  4. Choose how to authenticate. OAuth (recommended) — in your GitLab instance, add an application (Settings → Applications) with the read_api scope using the callback URL Brief shows you, then paste the Application ID and Secret into Brief and continue through the authorize flow. Access token — create a token with the read_api scope (Settings → Access Tokens) and paste it into Brief directly, no app registration needed.
  5. Select projects — pick which projects Brief should analyze, then toggle whether to include issue mining across the projects you selected
  6. Done! Brief starts syncing on a periodic schedule
If your instance uses an internal or self-signed certificate authority, ask your Brief admin to get it trusted at the org level — self-signed certs need that configuration before the connection can reach your server securely.

Common Issues

"Can't see my projects after connecting"

Cause: No projects were selected during setup, or the connected account lacks access. Fix: Go to Integrations → Manage next to GitLab and re-open project selection. Confirm the connecting account has at least read access to the projects you want.

"Merge requests aren't updating in real time (self-hosted)"

Cause: Self-hosted GitLab syncs periodically rather than via webhooks. Fix: This is expected — give it a sync cycle. If data is still stale after that, disconnect and reconnect to refresh the connection.

"OAuth app fields are missing (self-hosted)"

Cause: You're on the token path but tried to fill in Application ID/Secret, or vice versa. Fix: Use "Use an access token instead" or "Use OAuth instead" inside the connect dialog to switch modes — the fields shown depend on which path you're on.

"Certificate error connecting to my instance"

Cause: Your GitLab server uses a self-signed or internal CA certificate that Brief doesn't trust by default. Fix: Ask your Brief admin to get the certificate trusted at the org level, then retry the connection.

What's Next?

Now that GitLab is connected: