Skip to main content
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.

​
Step 1: Create a GitLab Access Token

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 (e.g. 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.

​
Step 2: Configure the Integration in OpenSRE

Run the setup wizard and select GitLab:
When prompted, enter:
  • GitLab base URL — leave as https://gitlab.com/api/v4 for GitLab.com, or change to your self-hosted instance URL (e.g. https://gitlab.example.com/api/v4)
  • GitLab access token — from Step 1
The wizard validates your token by calling the GitLab API and writes the following to your .env file: 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.

​
What the Agent Can Do

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

​
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. To enable it, set the following environment variable:
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

​
Troubleshooting

Validation fails with 401 Your token is invalid or has expired. Regenerate it in GitLab and re-run opensre onboard. Validation fails with 403 Your token does not have sufficient scopes. Ensure read_api is selected (and api if using write-back). Self-hosted instance not reachable Verify that GITLAB_BASE_URL ends in /api/v4 and that your OpenSRE server can reach the GitLab host. Test with:
MR write-back not posting Check that GITLAB_MR_WRITEBACK=true is set in your environment and that the alert payload contains gitlab.merge_request_iid and gitlab.project_id fields. Review OpenSRE server logs for [publish] GitLab MR entries.