# Releases

> **For agents:** `list_releases(org="acme")` shows version, status, commit, deploy count, last deploy, and artifact bundles; `create_release(org="acme", version="1.4.2", commitSha="a3f9c2e")` and `create_deploy(org="acme", version="1.4.2", environment="production")` need `release:write`; `get_release_health(org="acme", project="web", version="1.4.2")` returns the crash-free rate.

## Registering a release

A release is an organization-wide version string, matched against the `release` the SDK sends. Register it from CI:

```sh
curl -sS https://api.bugwatch.io/v1/orgs/acme/releases -H 'Authorization: Bearer bwt_…' \
  -H 'content-type: application/json' \
  -d '{"version":"1.4.2","commitSha":"a3f9c2e","url":"https://github.com/acme/web/releases/tag/v1.4.2"}'
```

Creating the same version again is an upsert — `commitSha` and `url` fill in if they were missing — so a CI job can run it on every build. Uploading an artifact bundle with `sentry-cli --release <version>` for an unknown version also creates it. `sentry-cli releases new` / `finalize` / `deploys` are **not** supported — only the artifact-bundle upload routes are implemented — so register releases and deploys with the REST routes below (or the `create_release` / `create_deploy` tools).

Then record where it went:

```sh
curl -sS https://api.bugwatch.io/v1/orgs/acme/releases/1.4.2/deploys -H 'Authorization: Bearer bwt_…' \
  -H 'content-type: application/json' -d '{"environment":"production","name":"eu-west","url":"https://…"}'
```

`GET /v1/orgs/{org}/releases` lists the latest 100 releases with `status` (`open`), `deploys`, `lastDeployedAt`, `artifactBundles`, and `commitSha`.

## What releases unlock

- **Symbolication** by release + URL path for maps uploaded without debug IDs ([Source maps](https://docs.bugwatch.io/sdks/source-maps.md)).
- **Fix context**: `get_fix_context` includes the release and its commit so an agent knows which revision to diff against.
- **Regressions**: an issue resolved *in* release X regresses only when a semver-newer release reproduces it ([Issues](https://docs.bugwatch.io/product/issues.md)).
- **Alert filters**: rules can match `release` with a pattern such as `2.*`.
- **Release check**: the `release_check` prompt combines health, new/regressed issues since the deploy, and the p95/failure delta.

## Release health

Mobile and browser SDKs send **sessions** with a status. Bugwatch indexes them per release and reports, for the last 7 days:

```json
{
  "release": "1.4.2",
  "sessions": { "total": 18240, "init": 18240, "exited": 17990, "errored": 190, "crashed": 55, "abnormal": 5 },
  "crashFreeRate": 0.99698,
  "note": "sampling-weighted; treat as ≈"
}
```

`total` is the number of sessions that started (`init`); crash-free = 1 − crashed / init. Server SDKs rarely send sessions, in which case `crashFreeRate` is `null` — that is "no data", not "100%". Sessions are free and do not count toward the event meter.

## Recommended CI order

1. Build with the release string in the environment (`RELEASE=$GIT_SHA`).
2. `sentry-cli --url https://api.bugwatch.io sourcemaps upload --release $GIT_SHA …` (creates the release if needed).
3. `POST /v1/orgs/{org}/releases` with the commit SHA and URL.
4. Deploy, then `POST …/releases/{version}/deploys`.
5. Optionally run the `release_check` prompt 15–30 minutes later.