Skip to main content

​
Overview

OpenSRE’s GitLab integration gives the investigation agent read access to your merge requests, commits, pipelines, and files for root cause analysis. Optionally, it can write investigation findings back as a note on the relevant MR.

​
Prerequisites

  • GitLab.com or a self-hosted GitLab instance reachable from OpenSRE
  • A Personal Access Token or Project Access Token
  • Scopes: read_api (required); api only if you enable MR write-back

​
Setup

​
Option 1: Interactive CLI

You can also select GitLab from opensre onboard. When prompted, enter:
  • GitLab base URL — leave as https://gitlab.com/api/v4 for GitLab.com, or change to your self-hosted instance URL (for example https://gitlab.example.com/api/v4)
  • GitLab access token — from Credentials below
The wizard validates your token by calling the GitLab API and writes credentials to your environment / store.

​
Option 2: Environment variables

GitLab tools use this configured integration for the base URL and token. Do not pass gitlab_url or gitlab_token as tool arguments; those values are resolved from the integration configuration. A self-hosted instance host such as https://gitlab.example.com is normalized to https://gitlab.example.com/api/v4.

​
Credentials

OpenSRE supports both Personal Access Tokens and Project Access Tokens. A Project Access Token is recommended for production — it is scoped to a single project and does not depend on a user account.

​
Personal Access Token (quickest for local use)

  1. In GitLab, go to your avatar → Edit profile → Access Tokens.
  2. Click Add new token.
  3. Give it a name (for example opensre) and set an expiry date.
  4. Select the following scopes:
    • read_api — required for reading MRs, commits, pipelines, and files
    • api — required only if you enable MR write-back (posting findings as MR notes)
  5. Click Create personal access token and copy the value immediately — it is shown only once.
  1. Open your GitLab project → Settings → Access Tokens.
  2. Click Add new token.
  3. Give it a name, set a role of Reporter (or Developer if write-back is needed), and select the same scopes as above.
  4. Click Create project access token and copy the value.
If your GitLab instance is self-hosted, make sure your OpenSRE server can reach it over the network before proceeding.

​
Investigation tools

Once connected, OpenSRE automatically uses GitLab as an investigation source when an alert contains a GitLab MR reference.

​
Use GitLab tools in the interactive shell

After connecting GitLab, include a GitLab project or file URL in your request. OpenSRE infers the project scope from the current message and keeps it for follow-up questions in the same session.
Project URLs enable commits, merge request, and pipeline tools:
OpenSRE also checks recent conversation, GITLAB_PROJECT_ID, GITLAB_REF, GITLAB_FILE_PATH, and the current repository’s GitLab origin remote when the current message does not contain a URL.

​
MR write-back (optional)

OpenSRE can post a formatted investigation summary directly as a note on the GitLab MR that triggered the alert. This is opt-in and disabled by default.
When enabled, after each investigation OpenSRE posts a collapsible ### RCA Finding note on the MR. The note is truncated to 4000 characters if needed. Requirements for write-back:
  • Your access token must have the api scope (not just read_api)
  • The alert payload must include a GitLab MR IID and project ID so OpenSRE can identify the target MR

​
Verify

​
Troubleshooting

​
Security

  • Prefer a Project Access Token with Reporter for read-only investigations.
  • Enable api / Developer only when you need MR write-back.
  • Store tokens in .env or your secret manager — not in source control.
  • Keep write-back off (GITLAB_MR_WRITEBACK unset) unless you intentionally want RCA notes on MRs.