Integrate Sentry into CI/CD pipelines for automated release creation,
source map uploads, and deploy notifications.
Use when setting up GitHub Actions, GitLab CI, or CircleCI to automate
Sentry releases, upload source maps, or associate commits with deploys.
Trigger with phrases like "sentry github actions", "sentry CI pipeline",
"automate sentry releases", "sentry source map upload CI",
"sentry gitlab ci", "sentry circleci".
Instrucciones de origen · Vista previa de solo lectura
name
sentry-ci-integration
description
Integrate Sentry into CI/CD pipelines for automated release creation,
source map uploads, and deploy notifications.
Use when setting up GitHub Actions, GitLab CI, or CircleCI to automate
Sentry releases, upload source maps, or associate commits with deploys.
Trigger with phrases like "sentry github actions", "sentry CI pipeline",
"automate sentry releases", "sentry source map upload CI",
"sentry gitlab ci", "sentry circleci".
Designed for Claude Code, also compatible with Codex and OpenClaw
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.
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.
# 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:
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.
# 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.
# 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:
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_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
# .github/workflows/deploy.ymlname:DeploywithSentryReleaseon: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-lateststeps:-uses:actions/checkout@v4with:fetch-depth:0# Full git history for commit association-uses:actions/setup-node@v4with:node-version:20-name:Installdependenciesrun:npmci-name:Buildwithsourcemapsrun:npmrunbuild-name:CreateSentryreleaseanduploadsourcemapsrun:|
VERSION="${{ github.sha }}"
npx @sentry/cli releases new "$VERSION"
npx @sentry/cli releases set-commits "$VERSION" --auto
npx @sentry/cli releases files "$VERSION" upload-sourcemaps ./dist \
--url-prefix '~/' \
--validate
npx @sentry/cli releases finalize "$VERSION"
npx @sentry/cli releases deploys "$VERSION" new -e production
-name:Deployapplicationrun:npmrundeploy
Using the official GitHub Action as a simpler alternative:
