Workflow: source-map uploads that survive every deploy

TL;DR

Use the exact version string your app reports as its release (package.json version, git SHA, whatever the SDK's release option sends). sentry-cli releases new "my-app@[version]" sentry-cli releases set-commits "my-app@[version]" --auto Do this in CI before the build. A mismatch here is the classic silent failure. Add a post-deploy smoke test that throws once and checks the issue appears resolved.

When to use

You are seeing this: Source-map uploads are a pipeline, not a command. Use this skill when you run into "Workflow: source-map uploads that survive every deploy".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

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.