Skip to main content
GitLab unifies issues, code review, CI and CD into a single UI. Connecting AppSignal to GitLab covers the same ground as the GitHub integration: GitLab is a personal integration: each user who wants to use it must complete the setup for themselves on every AppSignal app.
GitLab offers several ways to connect to third-party tools. AppSignal connects using a GitLab personal access token and your project URL, which is supported on GitLab.com, GitLab Self-Managed, and GitLab Dedicated. GitLab also offers OAuth applications, but AppSignal does not support connecting to GitLab over OAuth yet.
Website: https://gitlab.com

​
Step 1. Create a GitLab personal access token

  1. Sign in to GitLab and go to your user Settings.
  2. In the left sidebar, select Access tokens, then open Personal access tokens (https://gitlab.com/-/user_settings/personal_access_tokens on GitLab.com).
  3. Select Add new token. GitLab lets you create either a fine-grained or a legacy personal access token. Choose legacy, because its scopes map directly to what AppSignal needs.
  4. Fill in:
    • Token name: AppSignal
    • Expiration date: pick a date that matches your organization’s policy.
    • Scopes: select read_api, read_repository, and api. AppSignal needs all three.
  5. Select Create personal access token and copy the token immediately. GitLab only shows it once.
Creating an issue is a write action, so the read-only scopes are not enough on their own. On GitLab 15.5 and later, AppSignal doesn’t save a token without the api scope. It shows an error asking for a token that has it. Earlier versions of GitLab don’t report a token’s scopes, so AppSignal can’t check them.GitLab does not let you change a token’s scopes after you create it. To adjust them, create a new token and update the integration in AppSignal.
Fine-grained tokens may also work, but their resource permissions are far more granular and it is not obvious which combination to select. We’re planning to move this integration to GitLab OAuth applications, the more recent way to connect third-party tools to GitLab.

​
Step 2. Add the integration in AppSignal

  1. In AppSignal, open the app you want to connect.
  2. Go to App settings → Integrations. Under Personal issue tracker integrations, select Configure next to GitLab.
  3. Fill in the form:
    • Token: paste the personal access token you created in Step 1. The field’s hint names the scope AppSignal needs.
    • GitLab URL: the full URL to the GitLab project, for example https://gitlab.com/your-namespace/your-project. For GitLab Self-Managed, use your instance hostname, e.g. https://gitlab.example.com/your-group/your-project.
  4. Select Create integration.
You can return to this page at any time to Update integration or Remove integration. When new GitLab features need more permissions, AppSignal shows a banner asking you to update your GitLab token. Select Update GitLab token, and save a token with the scopes from Step 1.

​
Step 3. Repeat for each user

Because this is a personal integration, every teammate who wants source links, backtrace links, or issue creation to work in their own AppSignal account must repeat Steps 1 and 2 with their own GitLab token. Codebases change constantly, so a backtrace is most useful when it points at the revision that was deployed when the error happened. Connecting GitLab fills in the Repo URL for your app, so you don’t have to set it by hand. You can confirm it under App settings → General, where the field holds your GitLab project URL. AppSignal detects the provider from that URL and builds the matching backtrace and comparison links. Once deploy markers report the deployed revision, AppSignal links each backtrace line to the matching revision, path, and line in your GitLab repository, so you can go from an error to the code that shipped it. For the full setup, see the backtrace links documentation.

​
Create GitLab issues for incidents

AppSignal does not create GitLab issues automatically, to prevent story-overload. To create one for an error incident:
  1. Open the error incident’s details screen.
  2. In the Actions panel, select Send to GitLab.
AppSignal creates the issue in the linked GitLab project, and you can open it from the incident page afterwards. Creating issues requires a token with the api scope alongside the read scopes, described in Step 1.

​
Follow linked issues from the incident

This feature is in beta, as part of AppSignal Labs. Ask Support to turn it on for your organization.
The Actions panel shows a button for every linked GitLab issue, labeled View #123 in GitLab. Each button shows the issue’s status as a badge:
  • Premium and Ultimate: the status as GitLab names it, such as To do or a custom status like In review.
  • Free: Open or Closed.
An incident's Actions panel in AppSignal with a View #2 in GitLab button and an In progress status badge AppSignal updates the badge whenever the issue changes in GitLab. Status changes also show in the incident’s logbook. For example: Changed the status of #123 on GitLab from To do → In review. The entry shows who made the change in GitLab. A few limitations worth knowing:
  • A new issue gets its badge shortly after you send it to GitLab, once GitLab tells AppSignal about it.
  • Issues sent to GitLab before this feature show no badge until they next change in GitLab.
  • The logbook doesn’t show an issue’s first status, because there’s no earlier status to compare it with.

​
Turn on status updates

GitLab sends status changes to AppSignal through a webhook on your GitLab project. AppSignal adds it when you save the integration:
  1. Go to App settings → Integrations, and select Configure next to GitLab.
  2. Select Update integration. If the integration is new, select Create integration.
You need the Maintainer or Owner role on the GitLab project. Without it, the integration still saves. AppSignal then shows: “Two-way sync is off: AppSignal couldn’t add a webhook to this GitLab project.” Ask a Maintainer to save the integration, or get the role and save it again.

​
Switch projects or remove the integration

  • Switching to another GitLab project: save the integration with the new project’s URL. AppSignal moves its webhook to the new project. You need the Maintainer or Owner role on the new project.
  • Removing the integration: AppSignal keeps the webhook while anyone else on the app still uses the integration. It removes the webhook when the last person removes it.

​
Deploy markers from GitLab CI/CD

To report deployments to AppSignal from a GitLab CI/CD pipeline, see the deploy markers documentation for the recommended revision config option approach, or the Markers API example if your stack does not include an AppSignal integration.

​
Troubleshooting

AppSignal says the token doesn’t have the api scope. AppSignal needs api to create issues. GitLab doesn’t let you edit a token’s scopes. Create a new legacy token with read_api, read_repository, and api, and save it in AppSignal. Sending an incident to GitLab fails. The token may not have the api scope. AppSignal can’t check this for tokens saved before it started checking scopes, or on GitLab before 15.5. Create a new token with all three scopes and update the integration in AppSignal. Linked issues show no status badge. Confirm the GitLab project has the AppSignal webhook, under Settings → Webhooks in GitLab. If it’s missing, a Maintainer saves the integration again, as in Turn on status updates. AppSignal couldn’t remove its webhook. A Maintainer of the GitLab project can delete it under Settings → Webhooks in GitLab. AppSignal reports the GitLab integration as invalid. Check which scopes the token actually has. read_registry and read_repository sit next to each other in GitLab’s scope list, and a token that grants read_registry instead of read_api cannot read your project. Source links in AppSignal don’t open the correct file. In AppSignal, go to App settings → Integrations and select Configure next to GitLab. Confirm the GitLab URL points to the project root (e.g. https://gitlab.com/namespace/project), not to a subpath, branch, or .git URL.

​
Integrations list