> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitLab

> Connect AppSignal to your GitLab project to view source, link backtraces to revisions and lines, and create GitLab issues for incidents.

GitLab unifies issues, code review, CI and CD into a single UI.

Connecting AppSignal to GitLab covers the same ground as the [GitHub integration](/application/integrations/github):

* [Link AppSignal to your GitLab repository](#link-appsignal-to-your-gitlab-repository), so AppSignal knows where your code lives.
* [Link backtraces to revisions and lines](#link-backtraces-to-revisions-and-lines), so every backtrace line opens the code that shipped.
* [Create GitLab issues for incidents](#create-gitlab-issues-for-incidents), straight from an incident's details screen.

GitLab is a **personal integration**: each user who wants to use it must complete the setup for themselves on every AppSignal app.

<Note>
  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.
</Note>

Website: [https://gitlab.com](https://gitlab.com)

<h2 id="link-appsignal-to-your-gitlab-repository">
  Link AppSignal to your GitLab repository
</h2>

<h3 id="step-1-create-a-gitlab-personal-access-token">
  Step 1. Create a GitLab personal access token
</h3>

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.

<Warning>
  Creating an issue is a write action, so the read-only scopes are not enough on
  their own. A token with only `read_api` and `read_repository` connects and links
  source, but GitLab rejects the request when you send an incident. Add `api` to
  create GitLab issues from AppSignal.

  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.
</Warning>

<Note>
  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.
</Note>

<h3 id="step-2-add-the-integration-in-appsignal">
  Step 2. Add the integration in AppSignal
</h3>

1. In AppSignal, open the app you want to connect.
2. Go to **App settings → Integrations → GitLab**.
3. Fill in the form:
   * **Token**: paste the personal access token you created in Step 1.
   * **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**.

<h3 id="step-3-repeat-for-each-user">
  Step 3. Repeat for each user
</h3>

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.

<h2 id="link-backtraces-to-revisions-and-lines">
  Link backtraces to revisions and lines
</h2>

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](/application/markers/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](/application/backtrace-links).

<h2 id="create-gitlab-issues-for-incidents">
  Create GitLab issues for incidents
</h2>

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](#step-1-create-a-gitlab-personal-access-token).

<h2 id="deploy-markers-from-gitlab-ci/cd">
  Deploy markers from GitLab CI/CD
</h2>

To report deployments to AppSignal from a GitLab CI/CD pipeline, see the [deploy markers documentation](/application/markers/deploy-markers#gitlab-support) for the recommended `revision` config option approach, or the [Markers API example](/application/markers/deploy-markers#gitlab-cicd-example) if your stack does not include an AppSignal integration.

<h2 id="troubleshooting">
  Troubleshooting
</h2>

**Sending an incident to GitLab fails.**
A token with read-only scopes connects successfully but cannot create issues. Confirm the token has `api` as well as `read_api` and `read_repository`. Because scopes can't be edited after a token is created, create a new legacy token with all three and update the integration in AppSignal.

**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.**
Re-open **App settings → Integrations → GitLab** in AppSignal and confirm the GitLab URL points to the project root (e.g. `https://gitlab.com/namespace/project`) and not to a subpath, branch, or `.git` URL.

<hr />

### Integrations list

* [Asana](/application/integrations/asana)
* [Discord](/application/integrations/discord)
* [Geckoboard](/application/integrations/geckoboard)
* [GitLab](/application/integrations/gitlab)
* [Google Hangouts Chat](/application/integrations/hangouts)
* [Jira](/application/integrations/jira)
* [Linear](/application/integrations/linear)
* [Microsoft Teams](/application/integrations/teams)
* [OpsGenie](/application/integrations/opsgenie)
* [PagerDuty](/application/integrations/pagerduty)
* [Shortcut](/application/integrations/shortcut)
* [Slack](/application/integrations/slack)
* [Squadcast](/application/integrations/squadcast)
* [Trello](/application/integrations/trello)
* [Webhooks](/application/integrations/webhooks)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.