Workflow: source-map uploads that survive every deploy

Workflow: source-map uploads that survive every deploy

Source-map uploads are a pipeline, not a command. Skip one step and production errors stay minified. The order matters: create, inject, upload, deploy, verify.

Step 1: create the release

sentry-cli releases new "my-app@[version]"
sentry-cli releases set-commits "my-app@[version]" --auto

Do this in CI before the build. Use the exact version string your app reports as its release (package.json version, git SHA, whatever the SDK's release option sends). A mismatch here is the classic silent failure.

Step 2: build with Debug ID injection

The Sentry bundler plugins inject a Debug ID into every bundle and map file. Do not hand-roll your own IDs; the injection must happen at build time so the error event and the artifact share the ID.

Step 3: upload the artifacts

sentry-cli sourcemaps upload --release "my-app@[version]" ./dist

Upload in the same CI job as the build, before deploy. Authenticate with an organization token stored as a CI secret; personal tokens break when the token owner leaves.

Step 4: deploy, then verify

After deploy, trigger a test error against the production build and check the issue: the stack trace should show real filenames and line numbers within minutes. If it does not, check the release's artifacts tab before anything else.

Guardrails

• Never set SENTRY_ALLOW_FAILURE (or its equivalent) to let builds pass when the upload fails. A green build with missing maps is worse than a red one.
• Upload from the same job that builds: source maps from a different revision will not match.
• Keep old releases' artifacts. Errors from users on cached old bundles need old maps.

Verify

The artifacts tab of the release shows the uploaded files with Debug IDs, and a fresh production error renders a readable stack trace. Add a post-deploy smoke test that throws once and checks the issue appears resolved.

Researched against live Sentry docs 2026-09-26. The JS source maps page (docs.sentry.io/platforms/javascript/sourcemaps/) documents uploading with sentry-cli, injecting Debug IDs, and verifying. The CLI configuration page (docs.sentry.io/cli/configuration/) documents auth via tokens and org tokens for CI. The releases product page (docs.sentry.io/product/releases/) documents release creation and associating commits.