sentry-ci-integration

What this skill does

# Sentry CI Integration

## Overview

Sentry releases connect errors to the code that caused them. Automating release creation in CI/CD ensures every deploy has commit association (suspect commits), source maps for readable stack traces, and deployment tracking across environments. This skill covers `sentry-cli` commands, the official GitHub Action, build tool plugins (`@sentry/webpack-plugin`, `@sentry/vite-plugin`, `@sentry/esbuild-plugin`), and multi-platform CI configurations.

## Prerequisites

- Sentry account with a project at [sentry.io](https://sentry.io)
- `SENTRY_AUTH_TOKEN` — generate at sentry.io/settings/auth-tokens/ with scopes `project:releases` and `org:read`
- `SENTRY_ORG` and `SENTRY_PROJECT` environment variables matching your organization and project slugs
- Source maps generated during your build step (`devtool: 'source-map'` in webpack, `build.sourcemap: true` in Vite)
- Git integration installed in Sentry (sentry.io/settings/integrations/ — GitHub, GitLab, or Bitbucket) for commit association
- `sentry-cli` available via `npm install -g @sentry/cli`, `npx @sentry/cli`, or the `getsentry/sentry-cli` Docker image

## Instructions

### Step 1 — Configure Environment Variables and Auth Token

Set up the three required environment variables in your CI platform. Every `sentry-cli` command reads these automatically.

```bash
# GitHub Actions — add as repository secrets:
#   Settings > Secrets and variables > Actions > New repository secret
SENTRY_AUTH_TOKEN=sntrys_eyJ...     # Internal integration token from sentry.io/settings/auth-tokens/
SENTRY_ORG=my-org                    # Organization slug (visible in sentry.io URL)
SENTRY_PROJECT=my-project            # Project slug (Settings > Projects > project name)

# Required token scopes:
#   project:releases   — create releases, upload source maps, record deploys
#   org:read           — read organization data for --auto commit association

# GitLab CI — add under Settings > CI/CD > Variables (masked + protected)
# CircleCI — add under Project Settings > Environment Variables
```

For build tool plugins (`@sentry/webpack-plugin`, `@sentry/vite-plugin`, `@sentry/esbuild-plugin`), the same three environment variables are read automatically. No additional configuration needed.

Verify your token works locally before committing CI configuration:

```bash
export SENTRY_AUTH_TOKEN=sntrys_eyJ...
export SENTRY_ORG=my-org
export SENTRY_PROJECT=my-project
npx @sentry/cli info
# Should print organization name, project, and CLI version
```

### Step 2 — Create the CI Release Pipeline

The release pipeline follows five commands in sequence: create release, associate commits, upload source maps, finalize release, and record deployment.

```bash
# The five sentry-cli commands that form a complete release pipeline:
VERSION=$(git rev-parse HEAD)

# 1. Create a new release (idempotent — safe to re-run)
sentry-cli releases new "$VERSION"

# 2. Associate commits for suspect commit detection (requires Git integration)
sentry-cli releases set-commits "$VERSION" --auto

# 3. Upload source maps with validation
sentry-cli releases files "$VERSION" upload-sourcemaps ./dist \
  --url-prefix '~/' \
  --validate

# 4. Mark the release as complete
sentry-cli releases finalize "$VERSION"

# 5. Record the deployment environment
sentry-cli releases deploys "$VERSION" new -e production
```

The `--validate` flag on source map upload checks that each `.map` file references a valid source file and that `sourceMappingURL` comments point to uploaded artifacts. Always use it in CI to catch mismatches early.

The `--url-prefix` must match the URL path where your JavaScript files are served. For example, if your app serves `https://example.com/assets/app.js`, use `--url-prefix '~/assets/'`. The `~/` prefix is shorthand for your domain root.

### Step 3 — Integrate Build Tool Plugins (Alternative to sentry-cli)

Build tool plugins handle source map upload during the build step itself, eliminating the need for separate `sentry-cli` commands. They automatically create releases, upload maps, and optionally delete `.map` files from the output so they are never served to clients.

**Vite** (`@sentry/vite-plugin`):

```javascript
// vite.config.js
import { sentryVitePlugin } from '@sentry/vite-plugin';

export default {
  build: {
    sourcemap: true, // Required — plugin needs source maps to upload
  },
  plugins: [
    sentryVitePlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
      release: {
        name: process.env.GITHUB_SHA || process.env.CI_COMMIT_SHA,
        setCommits: { auto: true },
        deploy: { env: process.env.NODE_ENV || 'production' },
      },
      sourcemaps: {
        filesToDeleteAfterUpload: ['./dist/**/*.map'],
      },
    }),
  ],
};
```

**Webpack** (`@sentry/webpack-plugin`):

```javascript
// webpack.config.js
const { sentryWebpackPlugin } = require('@sentry/webpack-plugin');

module.exports = {
  devtool: 'source-map',
  plugins: [
    sentryWebpackPlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
      release: {
        name: process.env.GITHUB_SHA || process.env.CI_COMMIT_SHA,
        setCommits: { auto: true },
        deploy: { env: 'production' },
      },
      sourcemaps: {
        assets: ['./dist/**'],
        filesToDeleteAfterUpload: ['./dist/**/*.map'],
      },
    }),
  ],
};
```

**esbuild** (`@sentry/esbuild-plugin`):

```javascript
// build.mjs
import { sentryEsbuildPlugin } from '@sentry/esbuild-plugin';
import esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['./src/index.ts'],
  bundle: true,
  sourcemap: true,
  outdir: './dist',
  plugins: [
    sentryEsbuildPlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
      release: {
        name: process.env.GITHUB_SHA,
      },
    }),
  ],
});
```

Install the plugin for your build tool:

```bash
# Pick one based on your build tool:
npm install --save-dev @sentry/vite-plugin
npm install --save-dev @sentry/webpack-plugin
npm install --save-dev @sentry/esbuild-plugin
```

## Output

After completing CI integration, every deploy produces:

- A Sentry release named by commit SHA, visible at sentry.io under Releases
- Source maps uploaded and validated, enabling readable JavaScript stack traces
- Commits associated with the release, powering suspect commit detection in issue details
- A deployment record in Sentry with the target environment (production, staging, etc.)
- Source map files optionally deleted from build output when using build tool plugins

Verify the release was created:

```bash
sentry-cli releases list --org my-org --project my-project
# Shows recent releases with commit counts and deploy environments
```

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| `error: API request failed: 401 Unauthorized` | Auth token invalid, expired, or missing | Regenerate at sentry.io/settings/auth-tokens/ and update CI secret |
| `error: could not determine any commits to associate` | Git integration not installed or shallow clone | Install GitHub/GitLab integration at sentry.io/settings/integrations/ and set `fetch-depth: 0` in checkout |
| `error: could not find referenced source map` | `sourceMappingURL` comment missing from JS files | Verify `devtool: 'source-map'` (webpack) or `build.sourcemap: true` (Vite) is set |
| Source maps uploaded but stack traces still minified | `--url-prefix` does not match served URL paths | Open browser DevTools Network tab, check the URL path of your JS files, and set `--url-prefix` to match |
| `error: release already exists` | Re-running pipeline for same commit | Safe to ignore — `sentry-cli releases new` is idempotent; subsequent commands update the existing release |
| `error: org not found` | `SENTRY_O