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

HealOps 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. healops) 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 HealOps server can reach it over the network before proceeding.

​
Step 2: Configure the Integration in HealOps

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:

​
What the Agent Can Do

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

​
MR Write-back (optional)

HealOps 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 HealOps 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 HealOps can identify the target MR

​
Troubleshooting

Validation fails with 401 Your token is invalid or has expired. Regenerate it in GitLab and re-run healops 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 HealOps 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 HealOps server logs for [publish] GitLab MR entries.