sentry-cli releases new and finalize in CI
sentry-cli releases new <version> registers a release in Sentry; releases finalize marks it complete so issues are attributed to it.
A Sentry release is the anchor that links errors, source maps, and commits to a specific build. In CI you create it before uploading artifacts and finalize it after the deploy.
What it does
sentry-cli releases new creates a release object identified by a version string (often the git SHA). sentry-cli releases finalize sets its dateReleased, which Sentry uses to decide which release an event belongs to. Both need an auth token plus an org and project.
Common usage
export SENTRY_AUTH_TOKEN=... # from CI secrets
export SENTRY_ORG=acme
export SENTRY_PROJECT=web
VERSION=$(sentry-cli releases propose-version)
sentry-cli releases new "$VERSION"
# ... upload sourcemaps, set commits ...
sentry-cli releases finalize "$VERSION"Options
| Flag / env | What it does |
|---|---|
| SENTRY_AUTH_TOKEN | Auth token env var (required); or --auth-token |
| -o, --org / SENTRY_ORG | Organization slug |
| -p, --project / SENTRY_PROJECT | Project slug |
| releases propose-version | Print a sensible version (git HEAD SHA) |
| releases finalize <ver> | Mark the release as released |
| --url / SENTRY_URL | Base URL for self-hosted Sentry |
In CI
Store SENTRY_AUTH_TOKEN as a masked secret and inject SENTRY_ORG and SENTRY_PROJECT as env so every subcommand inherits them. Use propose-version so the release id matches the commit you deployed, which makes error-to-commit attribution work.
Common errors in CI
"error: Auth token is required for this request" means SENTRY_AUTH_TOKEN is unset or not passed to the step. "error: API request failed: organization or project not found" (HTTP 404) means SENTRY_ORG or SENTRY_PROJECT is wrong or the token lacks scope for that project. "error: 401 Unauthorized: Invalid token" means the token was revoked or truncated by a missing secret.