bugwatch docs

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:

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:

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).
  • 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).
  • 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:

{
  "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.

  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.