.svg)
.svg)
Documentation Index
Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
Use this file to discover all available pages before exploring further.
Introduction
The GitLab integration connects Rootly with GitLab through OAuth so your team can surface engineering context during incidents and automate issue tracking across both platforms. With the GitLab integration, you can:- Fetch recent commits from GitLab repositories through incident workflows
- Automatically track push events, merged merge requests, and deployment events as Rootly pulses
- Create and update GitLab issues directly from incident and action item workflows
- Enrich GitLab merge request links pasted into incident Slack channels with live status cards
- Connect to self-hosted GitLab instances in addition to gitlab.com
GitLab issues can be created from both incident workflows and action item workflows, making it easy to turn follow-up work into trackable GitLab tasks automatically.
Before You Begin
Before setting up the GitLab integration, make sure you have:- A Rootly account with permission to manage integrations
- A GitLab account with admin access to create OAuth applications
- The GitLab instance URL if you are using a self-hosted GitLab instance (must use HTTPS)
This integration uses OAuth 2.0. You will need to create an OAuth application in GitLab and paste the credentials into Rootly. Keep your application secret secure — it is encrypted at rest in Rootly.
Installation
Open the integrations page in Rootly
Navigate to the integrations page in your Rootly workspace and select GitLab.
Create an OAuth application in GitLab
In GitLab, go to User Settings → Applications (or Admin Area → Applications for instance-wide access) and create a new OAuth application.
| Field | Value |
|---|---|
| Redirect URI | https://rootly.com/auth/gitlab/callback |
| Scopes | api or read_api |
Use the
api scope to let Rootly automatically create webhooks on your repositories. If you prefer to manage webhooks yourself, use read_api instead.Paste your credentials into Rootly
After saving your GitLab application, copy the Application ID and Secret and paste them into Rootly.
https://). The default is https://gitlab.com.Select repositories to track
Optionally, specify the repository names you want Rootly to track for pulse events. If you leave this blank, Rootly will track all repositories accessible to the connected account.
Limiting tracked repositories reduces noise. Only pushes, merge requests, and deployments from listed repositories will appear as Rootly pulses.
Pulse Events
Rootly automatically ingests the following GitLab webhook events and records them as pulses on the incident timeline and service activity feed.Push Events
When a commit is pushed to any tracked repository, Rootly creates a pulse with:- Summary:
[GitLab][Push] Commit: {commit message} - Labels: repository name, action (push)
- Refs: commit SHA, short SHA, branch ref
Merge Request Events
When a merge request is merged, Rootly creates a pulse and posts an enriched card to any linked incident Slack channel with merge request details and status.- Summary:
[GitLab][MR] Merged: {source branch} - Labels: repository name, action (pr_merged)
- Refs: merge commit SHA, base branch
Even if an MR is not merged during an active incident, Rootly will enrich any GitLab merge request URL pasted into an incident Slack channel with a live status card showing the MR title, author, and current state.
Deployment Events
When a deployment event is received, Rootly creates a pulse tied to the associated environment.- Summary:
[GitLab][Deploy] Commit: {title} | {status} - Labels: repository name, action (deploy)
- Refs: short commit SHA
Issue Events
GitLab issue events are also ingested and converted to Rootly alerts with severity, state, and a link back to the GitLab issue.Workflow Actions
GitLab workflow actions are available in both incident workflows and action item workflows.Create a GitLab Issue
Creates a new issue in a specified GitLab repository. Available in incident and action item workflows.| Field | Description | Required |
|---|---|---|
| Repository | The GitLab repository to create the issue in | Yes |
| Issue Type | Type of issue: issue, incident, test_case, or task | No |
| Title | Issue title — supports Liquid templating (e.g. {{ incident.title }}) | Yes |
| Description | Issue body — supports Liquid templating | No |
| Labels | Comma-separated labels to apply | No |
| Due Date | Due date — supports Liquid templating | No |
Use Liquid variables like
{{ incident.title }}, {{ incident.severity }}, and {{ incident.url }} in the title and description to automatically populate issues with live incident context.Update a GitLab Issue
Updates an existing GitLab issue. Commonly used to close or reopen issues when an incident changes state.| Field | Description | Required |
|---|---|---|
| Issue ID | ID of the GitLab issue to update — supports Liquid templating | Yes |
| Issue Type | Type of issue to update | No |
| Title | Updated title | No |
| Description | Updated body | No |
| Labels | Updated labels | No |
| Due Date | Updated due date | No |
| Completion | Whether to close or reopen the issue — can be set to auto-map from incident status | Yes |
Set Completion to auto-map from incident status so GitLab issues close automatically when the linked Rootly incident is resolved, and reopen if the incident is reopened.
Get GitLab Commits
Fetches recent commits from one or more repositories and posts them to a Slack channel. Useful for surfacing recent code changes during incident investigation.| Field | Description | Required |
|---|---|---|
| Services | Services to fetch commits for (uses the service’s linked repository) | No* |
| Repository Names | Specific GitLab repository names to query | No* |
| Branch | Branch to fetch commits from | Yes |
| Past Duration | How far back to look (e.g. 2 hours, 1 day) | Yes |
| Post to Slack Channels | Slack channels to post results to | No |
Default Workflows
When GitLab is connected, Rootly can create the following default workflows to get you started:- Create a GitLab issue when an incident is declared — automatically opens a GitLab issue tied to the incident
- Update the GitLab issue when the incident is resolved — closes the linked issue when the incident closes
- Create a GitLab issue for each action item — turns follow-up tasks into GitLab issues automatically
- Update the GitLab issue when an action item is completed — keeps GitLab in sync as action items are closed
Troubleshooting
Webhooks are not being created for my repositories
Webhooks are not being created for my repositories
Rootly automatically creates webhooks when you add repository names to the integration settings. If webhooks are not appearing in GitLab, confirm that the OAuth application was created with the
api scope. The read_api scope does not allow Rootly to create webhooks on your behalf — you will need to create them manually if you use read_api.Pulses are not appearing for push or merge request events
Pulses are not appearing for push or merge request events
Check that the repository name is listed in the integration’s Repository Names field. Only events from listed repositories are tracked. Also verify that the GitLab webhook is active by checking Repository → Settings → Webhooks in GitLab and confirming the Rootly webhook URL appears there with recent delivery history.
GitLab merge request links are not being enriched in Slack
GitLab merge request links are not being enriched in Slack
Link enrichment applies to merge request URLs pasted into incident Slack channels. Confirm that the GitLab integration is connected and that the URL format matches a GitLab merge request (the path should contain
/merge_requests/). Personal or group access tokens are not supported — the integration must be connected via OAuth.Workflow actions fail with a repository not found error
Workflow actions fail with a repository not found error
The OAuth token must have access to the repository you are targeting. If the repository is in a group or namespace the connected user cannot access, the action will fail. Re-authenticate with a user or service account that has the appropriate permissions.
The integration disconnected after the connecting user left the team
The integration disconnected after the connecting user left the team
GitLab OAuth tokens are tied to the user who authorized the application. If that user is removed from your GitLab instance, the token becomes invalid. Reconnect the integration using a GitLab service account or bot user to avoid this in the future.
Self-hosted GitLab instance is not connecting
Self-hosted GitLab instance is not connecting
Make sure your instance URL starts with
https:// and does not have a trailing slash. Rootly does not support HTTP-only GitLab instances. Also confirm that your GitLab instance is reachable from the public internet, as Rootly needs to send webhook deliveries to it.Uninstall
To remove the GitLab integration, go to the integrations page in Rootly, find the GitLab account, and select Configure → Delete. This will disconnect the account and remove all Rootly-managed webhooks from your repositories.Related Pages
Incident Workflows
Automate GitLab issue creation and updates using incident workflow triggers.
Action Item Workflows
Automatically create and close GitLab issues as action items move through their lifecycle.
Pulses
Learn how deployment and commit events appear as pulses in Rootly.