Track Deployments in Sentry to Correlate Errors with Releases

Send release events from CI, tag each deploy with git SHA and environment, and use release stats to catch error-rate regressions within minutes.

~25 mindeployobservabilityci

Task

Wire release tracking so every deploy is visible in error dashboards and regressions are attributed to the exact release that caused them.

When to use this

Error rates rise every Tuesday but nobody can say which deploy caused it. Issues arrive without version context, and triage starts from zero each time.

Prerequisites

Sentry (or similar) with an SDK already reporting errors
CI access to the Sentry API token and the git SHA of each build
A deploy step able to notify the release endpoint

Steps

1. Create the release with full provenance.

SENTRY_RELEASE=$(git rev-parse --short HEAD) && curl -s -X POST "https://sentry.io/api/0/organizations/acme/releases/" -H "Authorization: Bearer $SENTRY_TOKEN" -d '{"version": "'$SENTRY_RELEASE'", "refs": [{"repository": "app", "commit": "'$GIT_SHA'"}]}'

Expected output: The release exists with its commit reference before any deploy runs, ready to receive events.

2. Tell the application which release it runs.

Sentry.init({
  release: process.env.SENTRY_RELEASE,
  environment: process.env.NODE_ENV,
});

Expected output: Every reported error is automatically stamped with the running release and environment, no per-event code needed.

3. Mark deploy moments in the release timeline.

curl -s -X POST "https://sentry.io/api/0/organizations/acme/releases/$SENTRY_RELEASE/deploys/" -H "Authorization: Bearer $SENTRY_TOKEN" -d '{"environment": "production"}'

Expected output: Error charts gain vertical deploy markers, making cause and effect visually immediate.

4. Watch the release-specific new-issue count.

curl -s "https://sentry.io/api/0/organizations/acme/releases/$SENTRY_RELEASE/" -H "Authorization: Bearer $SENTRY_TOKEN" | jq '{new: .newGroups, projects: [.projects[].name]}'

Expected output: The newGroups count for the release rises within minutes when a deploy introduces a fresh error signature.

5. Alert on regressions tied to releases.

rules:
  - name: release-regression
    condition: event.level:error and event.releases.last(1h)
    actions: notify-owners

Expected output: A spike of new errors in the hour after a deploy pages the owner of that release rather than the whole team.

Troubleshooting

Problem

Errors arrive with no release tag

Solution

The SDK initializes before the release variable is set; ensure the env var is present at process start, or pass release explicitly at init.

Problem

Release names inconsistent between CI and app

Solution

Generate the name once in CI, export it to both the API call and the runtime environment, so humans and machines agree on one string.

Problem

Deploy markers missing on charts

Solution

The deploy notification was skipped or used a different environment name; call the deploys endpoint in the same CI step that flips traffic.

Limitations

Release attribution depends on every service reporting the same release identifier; a mismatched one fragments the signal.
Correlation is not causation; a Tuesday error spike may still be a traffic pattern that deploy markers merely contextualize.

Errors without versions are noise

An error report without a release tag could come from any code that ever ran. Tagging every deploy with a release, wiring the SDK to report it, and marking deploy moments on charts converts error streams into versioned evidence. The payoff is speed: a regression that appears in the newGroups count within minutes of a deploy has an obvious suspect and an obvious rollback, instead of a Tuesday mystery.

# CI: create the release before deploying
SENTRY_RELEASE=$(git rev-parse --short HEAD)
curl -X POST "https://sentry.io/api/0/organizations/acme/releases/" \
  -H "Authorization: Bearer $SENTRY_TOKEN" \
  -d '{"version": "'$SENTRY_RELEASE'"}'

# Runtime: every error inherits the tag
Sentry.init({ release: process.env.SENTRY_RELEASE });

One name, generated once

The release identifier must be identical in three places: the API call that creates it, the runtime the SDK reads, and the deploy notification. Generate it once in CI, export it through both channels, and resist the urge to let the app compute its own version string, which is how environments drift into mismatched names.

New issues are the deploy verdict

Total error volume moves with traffic and is weak evidence; newGroups, the count of error signatures never seen before, is the number that answers did this deploy break something new. Checking it fifteen minutes after each release, with an alert when it spikes, gives deploys a verdict before the next one ships.