Graphic showing the GitLab and Sentry logos

Sentry is an error-tracking platform that lets you monitor issues in your production deployments. It supports most popular programming languages and frameworks.

GitLab is a Git-based DevOps platform to manage the entire software development lifecycle. GitLab can integrate with Sentry to display captured errors. In this article, we’ll use the two services to stay ahead of issues in a React application.

Getting Set up

GitLab and Sentry both have self-hosted and SaaS options. The steps in this guide apply to both variants. We’ll assume that you’ve already got a React project ready to use in your GitLab instance.

Log in to Sentry and click the “Create Project” button in the top-right corner. Click “React” under the “Choose a platform” heading. This lets Sentry tailor example code snippets to your project.

image of adding a new React project in Sentry

Choose when to receive alerts using the options beneath “Set your default alert settings.” Select “Alert me on every new issue” to get an email each time an error is logged. The “When there are more than” option filters out noise created by duplicate events in a given time window.

Give your project a name in the “Project name” field. Click “Create Project” to finish your setup.

Adding Sentry to Your Codebase

Now, you need to integrate Sentry with your React code. Add the Sentry library to your project’s dependencies using npm:

npm install @sentry/react

You’ll need to initialize Sentry as soon as possible in your app’s JavaScript. This gives Sentry visibility into errors that occur early in the React lifecycle. Add Sentry’s bootstrap script before your first ReactDOM.render() call. This is typically in index.js:

import App from "./App.js";
import React from "react";
import ReactDOM from "react-dom";
import * as Sentry from "@sentry/react";
    dsn: "my-dsn"
ReactDOM.render(<App />, document.getElementById("react"));

Replace my-dsn with the DSN that Sentry displays on your project creation screen. The DSN uniquely identifies your project so that the service can attribute events correctly.

Capturing Errors

Sentry will automatically capture and report unhandled JavaScript errors. Although it can’t prevent the crash, it lets you know that something’s gone wrong before the user report arrives.

Here’s an example App.js:

import React from "react";
export default () => {
    const data = null;
    return, key) => {
        <h1 key={key}>{val}</h1>;

This code is broken—data is set to null, so the map property will be undefined. We try to call regardless so that the app will crash. You should see an issue show up in Sentry.

Sentry issues include as much data about the error as possible. You can see the page URL as well as information about the user’s device. Sentry will automatically combine duplicate issues together. This helps you see whether an event was a one-off or a regular occurrence that’s impacting multiple users.

image of a Sentry error

Sentry automatically fetches JavaScript source maps when they’re available. If you’re using create-react-app, source maps are automatically generated by npm run build. Make sure that you copy them to your web server so that Sentry can find them. You’ll see pretty stack traces from the original source code instead of the obfuscated stack produced by the minified build output.

image of Sentry showing a stack trace from a source map

You can mark Sentry errors as Resolved or Ignored once they’ve been dealt with. You’ll find these buttons below the issue’s title and on the Issues overview page. Use Resolved once you’re confident that an issue has been fixed. Ignored is for cases where you don’t intend to address the root cause. In React sites, this might be the case for errors caused by old browser versions.

Error Boundaries

React error boundaries let you render a fallback UI when an error is thrown within a component. Sentry provides its own error boundary wrapper. This renders a fallback UI and logs the caught error to Sentry.

import * as Sentry from "sentry";
export default () => {
    const data = null;
    return (
        <Sentry.ErrorBoundary fallback={<h1>Something went wrong.</h1>}>
      , key) => {
                    <h1 key={key}>{val}</h1>;

Now, you can display a warning to users when an error occurs. You’ll still receive the error report in your Sentry project.

Adding GitLab Integration

There are two sides to integrating GitLab and Sentry. First, GitLab projects have an “Error Tracking” feature that displays your Sentry error list. You can mark errors as Resolved or Ignored from within GitLab. The second part involves connecting Sentry to GitLab. This lets Sentry automatically create GitLab issues when a new error is logged.

image of creating an API key in Sentry

Let’s look at GitLab’s Error Tracking screen first. You’ll need to create a Sentry API key. Click your username in the top left of your Sentry UI, and then the API Keys in the menu. Click “Create New Token” in the top-right corner.

Add the following token scopes:

  • alerts:read
  • alerts:write
  • event:admin
  • event:read
  • event:write
  • project:read

This allows GitLab to read and update your Sentry errors.

image of Sentry API token scopes

Next, head to your GitLab project. Click Settings in the side menu, and then Operations. Expand the “Error tracking” section. Paste your Sentry authentication token into the “Auth Token” field and press “Connect.” If you’re using a self-hosted Sentry instance, you’ll also need to adjust the “Sentry API URI” field to match your server’s URI.

image of GitLab's error tracking settings

The “Project” dropdown will populate with a list of your Sentry projects. Select the correct project and press “Save changes.” You’re now ready to use Error Tracking in GitLab.

Click Operations > Error Tracking in the left sidebar. You’ll see your Sentry error list. It’s filtered to Unresolved issues by default. This can be changed using the dropdowns in the top-right corner. Click an error to see its detailed stack trace without leaving GitLab. There are buttons to ignore, resolve, and convert to a GitLab issue. Once you’ve opened a GitLab issue, you can assign that item to a team member so that the bug gets resolved.

image of GitLab's Error Tracking screen

Now, you can add the second integration component—a link from Sentry back to GitLab. Click Settings in your Sentry sidebar, and then Integrations. Find GitLab in the list and click the purple “Add Installation” button in the top-right corner. Click “Next” to see the setup information.

image of adding the GitLab Sentry integration

Back on GitLab, click your user icon in the top-right corner, followed by “Preferences.” Click “Applications” in the left side menu and add a new application. Use the details shown by Sentry in the installation setup pop-up.

image of creating a new GitLab application integration

GitLab will display an Application ID and Secret Key. Return to the Sentry pop-up and enter these values. Add your GitLab server URL ( for GitLab SaaS) and enter the relative URL path to your GitLab group (e.g. my-group). The integration doesn’t work with personal projects.

image of adding the GitLab Sentry integration

Click the purple Submit button to create the integration. Sentry will now be able to display GitLab information next to your errors. This includes the commit that introduced the error, and stack traces that link back to GitLab files. Sentry users on paid plans can associate GitLab and Sentry issues with each other.

Disabling Sentry in Development

You won’t necessarily want to use Sentry when running your app locally in development. Don’t call Sentry.init() if you want to run with Sentry disabled. You can check for the presence of a local environment variable and disable Sentry if it’s set.

if (process.env.NODE_ENV === "production") {
        dsn: "my-dsn"

NODE_ENV is set automatically by create-react-app. Production builds hardcode the variable to production. You can use this to selectively enable Sentry.

Enabling Performance Profiling

Sentry can also profile your app’s browser performance. Although this isn’t the main focus of this article, you can set up tracing with a few extra lines in your Sentry library initialization:

npm install @sentry/tracing
import {Integrations} from "@sentry/tracing";
    dsn: "my-dsn",
    integrations: [new Integrations.BrowserTracing()],
    tracesSampleRate: 1.0

Now, you’ll be able to see performance data in your Sentry project. This can help you identify slow-running code in production.


Sentry lets you find and fix errors before users report them. You can get real-time alerts as problems arise in production. Stack traces and browser data are displayed inline in each issue, giving you an immediate starting point for resolution.

Combining Sentry with GitLab provides even tighter integration with the software development process. If you’re already using GitLab for project management, adding the Sentry integration lets you manage alerts within GitLab and create GitLab issues for new Sentry errors.

Profile Photo for James Walker James Walker
James Walker is a contributor to How-To Geek DevOps. He is the founder of Heron Web, a UK-based digital agency providing bespoke software development services to SMEs. He has experience managing complete end-to-end web development workflows, using technologies including Linux, GitLab, Docker, and Kubernetes.
Read Full Bio »