# 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.