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
SENTRY_AUTH_TOKEN — generate at sentry.io/settings/auth-tokens/ with scopes project:releases and org:readSENTRY_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.
SENTRY_AUTH_TOKEN=sntrys_eyJ...
SENTRY_ORG=my-org
SENTRY_PROJECT=my-project
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:
export SENTRY_AUTH_TOKEN=sntrys_eyJ...
export SENTRY_ORG=my-org
export SENTRY_PROJECT=my-project
npx @sentry/cli info
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.
VERSION=$(git rev-parse HEAD)
sentry-cli releases new "$VERSION"
sentry-cli releases set-commits "$VERSION" --auto
sentry-cli releases files "$VERSION" upload-sourcemaps ./dist \
--url-prefix '~/' \
--validate
sentry-cli releases finalize "$VERSION"
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):
import { sentryVitePlugin } from '@sentry/vite-plugin';
export default {
build: {
sourcemap: true,
},
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):
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):
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:
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:
sentry-cli releases list --org my-org --project my-project
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_ORG does not match organization slug | Check your org slug at sentry.io/settings/ (it appears in the URL) |
413 Request Entity Too Large | Source map bundle exceeds 40 MB upload limit | Split source maps per entry point or exclude vendor maps with --ignore flag |
| Build tool plugin silently skips upload | SENTRY_AUTH_TOKEN not set in CI environment | The plugins no-op when auth token is missing; ensure the secret is available to the build step |
Examples
Example A — GitHub Actions Full Release Workflow
name: Deploy with Sentry Release
on:
push:
branches: [main]
env:
SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Install dependencies
run: npm ci
- name: Build with source maps
run:
Using the official GitHub Action as a simpler alternative:
- name: Create Sentry release
uses: getsentry/action-release@v1
env:
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}
with:
environment: production
version: ${{ github.sha }}
sourcemaps: ./dist
url_prefix: '~/'
set_commits: auto
Example B — Vite Plugin with GitHub Actions
When using @sentry/vite-plugin, the build step handles source maps automatically. No separate sentry-cli step needed.
name: Deploy (Vite + Sentry Plugin)
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Install dependencies
run: npm ci
- name: Build (Vite plugin uploads source maps automatically)
run: npm run build
env:
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
SENTRY_ORG: ${{ secrets.SENTRY_ORG
import { sentryVitePlugin } from '@sentry/vite-plugin';
export default {
build: { sourcemap: true },
plugins: [
sentryVitePlugin({
org: process.env.SENTRY_ORG,
project: process.env.SENTRY_PROJECT,
authToken: process.env.SENTRY_AUTH_TOKEN,
release: {
name: process.env.GITHUB_SHA,
setCommits: { auto: true },
deploy: { env: 'production' },
},
sourcemaps: {
filesToDeleteAfterUpload: ['./dist/**/*.map'],
},
}),
],
};
Example C — GitLab CI
stages:
- build
- deploy
- sentry
build:
stage: build
image: node:20
script:
- npm ci
- npm run build
artifacts:
paths:
- dist/
sentry-release:
stage: sentry
image: getsentry/sentry-cli:latest
variables:
SENTRY_AUTH_TOKEN: $SENTRY_AUTH_TOKEN
SENTRY_ORG: $SENTRY_ORG
SENTRY_PROJECT: $SENTRY_PROJECT
script:
- VERSION="$CI_COMMIT_SHA"
- sentry-cli releases new "$VERSION"
- sentry-cli releases set-commits "$VERSION" --auto
- sentry-cli releases files "$VERSION"
Example D — CircleCI
version: 2.1
jobs:
deploy:
docker:
- image: cimg/node:20.0
steps:
- checkout
- run: npm ci
- run: npm run build
- run:
name: Create Sentry release
command: |
npm install -g @sentry/cli
VERSION="$CIRCLE_SHA1"
sentry-cli releases new "$VERSION"
sentry-cli releases set-commits "$VERSION" --auto
sentry-cli releases files "$VERSION" upload-sourcemaps ./dist \
--url-prefix '~/' \
--validate
sentry-cli releases finalize "$VERSION"
sentry-cli releases deploys "$VERSION" new -e production
workflows:
deploy:
jobs:
- deploy:
filters:
branches:
only: main
Example E — Monorepo with Multiple Sentry Projects
jobs:
deploy-api:
runs-on: ubuntu-latest
env:
SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- run: npm ci --workspace=api && npm run build --workspace=api
- name: Sentry release for API
run: |
VERSION="api@${{ github.sha }}"
npx @sentry/cli releases new "$VERSION" --project api-backend
npx @sentry/cli releases set-commits "$VERSION" --auto
npx @sentry/cli releases files "$VERSION" upload-sourcemaps ./api/dist \
--project api-backend --validate
npx @sentry/cli releases finalize "$VERSION"
npx @sentry/cli releases deploys "$VERSION" new -e production
deploy-web:
runs-on: ubuntu-latest
env:
SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
SENTRY_AUTH_TOKEN:
Resources
Next Steps
- sentry-deploy-integration — connect deploy notifications from Vercel, Netlify, or AWS to Sentry releases
- sentry-release-management — version naming strategies, release health monitoring, and regression detection
- sentry-debug-bundle — upload debug information files (dSYMs, ProGuard mappings) for native crash symbolication
- sentry-performance-tracing — add distributed tracing to correlate releases with performance regressions
