Releases, deploys and release health
A release is a version string your code reports (release on every event, and on every
session). Registering it, and recording where it was deployed, is what turns that string
into "what shipped, who wrote it, and where is it live".
# Register the release with the commit it was built from.
curl -X POST "$API/orgs/$ORG/projects/$PROJECT/releases" \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"version":"4.2.0","commitSha":"<40-hex sha>"}'
# Record a deploy of it.
curl -X POST "$API/orgs/$ORG/projects/$PROJECT/releases/4.2.0/deploys" \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"environment":"production"}'
Or, from CI, with the bucker CLI (cli.md), which does the same with retries,
source maps and a verify gate:
bucker releases new "$VERSION" --commit "$GIT_SHA"
bucker sourcemaps upload dist --release "$VERSION" # fails the job if a shipped id cannot resolve
bucker releases finalize "$VERSION"
bucker deploys new "$VERSION" --env production
CI recipes
All three recipes run the four commands above, in that order. Each takes the token from the
CI system's secret store. Use an org CI token (bkr_org_…, Settings → Tokens, scopes
project:read and release:write): it is not bound to a person, so the pipeline keeps working
after they leave. The files are in code/tooling/release-action/, and
tooling/bucker-cli/test/ci-recipes.test.ts runs each command in them through the real CLI.
GitHub Actions: the composite action bucker/release-action:
- run: npm run build
- uses: bucker/release-action@v0
with:
token: ${{ secrets.BUCKER_TOKEN }}
org: acme
project: web
sourcemaps: dist # omit to skip source maps
environment: production # '' records no deploy
GitLab CI/CD: a CI/CD component. BUCKER_TOKEN is a masked, protected CI/CD variable:
include:
- component: $CI_SERVER_FQDN/<group>/bucker-release/release@0.1.0
inputs:
org: acme
project: web
sourcemaps: dist
AWS CodeBuild: merge this into your buildspec.yml. The token comes from Secrets Manager:
env:
variables: { BUCKER_ORG: acme, BUCKER_PROJECT: web, CLI: '@bucker/cli@0.1.0' }
secrets-manager:
BUCKER_TOKEN: bucker/ci:token
phases:
post_build:
commands:
- export BUCKER_RELEASE="${BUCKER_RELEASE:-$CODEBUILD_RESOLVED_SOURCE_VERSION}"
- npx --yes "$CLI" releases new "$BUCKER_RELEASE" --commit "$CODEBUILD_RESOLVED_SOURCE_VERSION"
- npx --yes "$CLI" sourcemaps upload dist --release "$BUCKER_RELEASE"
- npx --yes "$CLI" releases finalize "$BUCKER_RELEASE"
- npx --yes "$CLI" deploys new "$BUCKER_RELEASE" --env production
What shipped in a release
When a release is registered with a commitSha, Bucker walks the commits between the
previous release's commit and this one's and stores them. The release page lists them,
newest first, with author, time and the files each touched.
GET …/releases/{version}/commits returns the same list.
The walk uses your connected repository through the SCM provider. It needs a repository connected for the organization and a code mapping for the project (the same mapping suspect commits use). Where the provider cannot compare two commits, Bucker falls back to the commits your repository webhook already delivered between the two releases and says so on the page.
A release never shows a bare empty list. The page states why it is empty:
| Status | Meaning and what to do |
|---|---|
no_commit_sha |
The release was registered without commitSha. Register it again with one. |
no_repository |
No repository is mapped to the project. Connect one and add a code mapping. |
consent_revoked |
Access to the mapped repository was revoked. |
app_not_configured |
The repository is connected through a GitHub App installation and this deployment has no GitHub App configured (GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY). Connect the repository with a token instead. |
provider_unavailable |
The provider could not be reached. Use Refresh (POST …/releases/{version}/sync-commits). |
commit_not_found |
The release's commit is in none of the mapped repositories. |
no_baseline |
No earlier release carries a commit, so only this release's own commit is known. |
How a deploy ended
Every deploy has an outcome: a status, a duration, a source and a rollback flag,
shown on the release page's deploys table and returned by GET …/releases, list_releases and
the deploy routes.
# Open a deploy when the rollout begins, then settle it when it ends.
ID=$(bucker deploys new "$VERSION" --env production --service api --status started --json | jq -r .id)
# … roll out …
bucker deploys finish "$ID" --status succeeded # or failed
| Status | Meaning |
|---|---|
STARTED |
Opened with --status started; not yet finished. |
SUCCEEDED |
Finished well. Also what a deploy reported without a status is stored as. |
FAILED |
Finished badly. A failed deploy shipped nothing: it is never the suspect deploy of an issue and does not count toward the rollback rule. |
UNKNOWN |
Nobody finished it. A STARTED deploy with no finish after two hours reads UNKNOWN, never SUCCEEDED, and delivery metrics count it as unmeasured. |
A report with no status keeps meaning what it always meant, "this deploy happened": it is stored
SUCCEEDED with finishedAt equal to deployedAt and the basis reported, so existing
pipelines are unchanged. Only a deploy opened as STARTED can time out. The basis says how
Bucker knows the status: reported, finished (an explicit finish), finished_late (a finish
that arrived after the timeout), timeout, or contradicted.
A later report never rewrites a final status. If a second source says FAILED about a deploy
already SUCCEEDED, the stored status stands, the row is flagged contradicted, and the report is
kept beside it on the deploy's change event, so both are visible.
bucker deploys new reads TRACEPARENT (its trace id becomes the deploy's ciTraceId, linking
the deploy to the pipeline run) and BAGGAGE (cicd.pipeline.run.id, cicd.pipeline.run.url.full
and service.name) from the environment. Anything malformed is ignored, never an error. A flag
always wins over the environment.
One deploy, however many reports
A deploy is identified by its release, its environment and its provider deployment id or
commit SHA (and service). The CLI and a platform or GitHub report of the same deploy are one
row: the row's source is whoever reported first, and the deploy's sources list names every
feed. A report that carries neither id nor SHA is matched by (release, environment, deployedAt)
as before. A later report fills in a column the first left empty and never blanks one it set.
Rollbacks
isRollback is true when the version equals an earlier version deployed to this environment
and differs from the previous deploy's. The rule is printed on the row (rollbackRule). Each
service is its own track, and a failed deploy is neither previous nor earlier.
Versions that only appeared
When a (service, environment, version) first shows up in telemetry with no deploy reported for
it, Bucker records an inferred version start on the change stream: a DEPLOY change event
whose metadata.source is observed. It is never a deploy row, has no outcome, and is never
counted as a deployment.
The deploy verdict
Each production deploy that SUCCEEDED gets a verdict once the 60 minutes after it finished have passed, from two checks that need no spans and no service entity:
| Check | Fails when |
|---|---|
| New error types | at least one fingerprint first seen in this release reached 5 events from 2 users within 60 minutes of the deploy finishing |
| Crash-free sessions | the release's crash-free sessions are lower than the previous release's at the same stage, with 500 sessions on each side and one-sided two-proportion p ≤ 0.01 (the staged-rollout guardian's test) |
Each check answers passed, failed, not_enough_data (a project with ten sessions is told so,
never told it passed) or not_checked. A not_enough_data verdict is re-judged for six hours as
sessions arrive; a passed or failed one is final. A failed verdict opens one ordinary issue,
exception type ReleaseVerdictFailed, grouped by project, environment and version, so it alerts,
assigns and reaches root-cause analysis like any other. Nothing acts on its own: halting or rolling
back stays a person's decision. No model takes part. The detector is release_verdict in
detectors_list: live, precision not measured, thresholds published.
Finishing a deploy
POST …/deploys/{deployId}/finish with { "status": "SUCCEEDED" | "FAILED", "finishedAt"? } needs
release:write (an org CI token or a person) and is audited deploy.update. A deploy of another
project is a 404.
Deploy diff
Each deploy row has a Changes button: the commits this deploy carried into its
environment, that is, the release's range minus what the environment already ran
(GET …/deploys/{deployId}/diff).
Suspect commits
Once a release's commits are recorded, the suspect commits of an issue are drawn from the range of the release the issue was first seen in. A commit outside that release cannot be the cause. An issue whose first release has no recorded range keeps the 14-day window.
Resolving by release
An issue resolved without a release reopens on its very next event, including the tail of the deploy that still has the bug. Pinned to a release, only an event from a later release reopens it. There are three ways to pin without knowing the version yet.
Resolve in the next release
Resolve in release… has a Resolve in next release button. The fix is merged but not
released: the issue stays resolved, nothing reopens it, and the first release registered after
that moment becomes its fix. The activity feed records the moment it binds ("The next release
arrived: now resolved in 4.2.0"). Over the API this is {"action":"resolve","resolvedInRelease":"@next-release"}.
A release is "registered" when POST …/releases creates it, or when the first event naming a
new version arrives.
Resolve from a commit message
A push to the repository's default branch whose commit message says
fixes BKR-123, closes BKR-123, BKR-124 or resolves BKR-123 resolves those issues in the
next release, with an activity row naming the commit. Only the project that repository is mapped
to is searched, so another project's BKR-123 is never touched. Issues already resolved
keep their release, and archived issues stay archived. A bare mention (see BKR-123) resolves nothing.
The commit message is what is read, which includes the title Git hosts write for a squash or
merge commit. The body of a pull request is not.
Auto-resolve on deploy (opt-in)
Settings › Projects › Release settings › Auto-resolve issues quiet for (days). With a value
set, recording a new deploy (POST …/releases/{version}/deploys) resolves the project's open
issues that have not been seen for that many days, pinned to the deployed release; the activity
row says which deploy and how long they had been quiet. Empty means off, which is the default.
Archived issues are never touched. GET/PUT …/release-settings is the same setting over the API.
Release-health alerts and a stability target
Alert on crash-free rate and adoption
A metric alert rule can watch three release-health rates, through the same router, channels, debounce and history as every other alert:
| Aggregate | Value |
|---|---|
crash_free_sessions |
1 - crashed / sessions for the release being watched |
crash_free_users |
1 - crashed users / users (needs identified users; server-SDK aggregates carry none) |
release_adoption |
the release's share of the project's sessions in the window |
All three are rates between 0 and 1, so the threshold is 0.995, not 99.5. Use the
lt comparator to alert when one drops:
{ "id": "metric", "aggregate": "crash_free_sessions", "comparator": "lt",
"threshold": 0.995, "windowMinutes": 180, "minSessions": 200 }
- Which release. The latest one in the environment: the release whose first session
bucket is most recent, so the rule follows your project through its releases without
being edited. A
releasefilter (equals) pins it to one version; anenvironmentfilter narrows the sessions read. Alevelfilter is refused, since sessions have no level. - No reading is not a breach. With fewer than
minSessionssessions (users, forcrash_free_users) in the window, default 100, the rule reports "no reading" and neither fires nor records a recovery. Two crashes in the first five sessions of a rollout is not an incident. - Freshness. Sessions and adoption read the same hourly rollup the release pages read, so a reading is at most one rollup pass old, and the alert and the page cannot disagree. Users are counted from the session table.
- The anomaly (learned-band) condition is not offered for these rates.
In the rule editor, choose a metric rule and the aggregate under Aggregate.
Stability target
Settings › Projects › Release settings › Crash-free sessions target (%) is an opt-in target for
the project, for example 99.5. It is shown on every release page as met or missed against that
release's own crash-free session rate, and the staged-rollout guardian uses it: a rollout
whose cohort has at least the sample floor of sessions and misses the target beyond chance (a
one-sided test at the guardian's p-value ceiling) halts with the verdict BELOW_TARGET, with or
without a baseline release to compare against. Leave it empty and the guardian judges by the
baseline alone, as before. Over the API: GET/PUT …/release-settings (crashFreeTarget, a rate).
Comparing releases, and the suspect deploy
Compare with another release
The release page has a Compare with another release panel. Pick any other release (the
predecessor is offered first) and the page puts the two side by side on crash-free sessions and
users, adoption, issues the release introduced, issues it brought back (regressions whose event
carried this release) and issues pinned as resolved in it, and the p95 duration of its root spans
(the last 30 days). The change column is computed on the server:
GET …/release-compare?base=&head=&environment=.
These are each release's own totals over its whole life. That is the right question for "which release was the worse one", and a different one from the comparison above it on the page, which asks whether a release is worse than its predecessor was at the same point in its rollout (the question the staged-rollout guardian halts on). A figure with nothing behind it, such as no sessions or no spans, is shown as a dash, never as zero.
Suspect deploy on an issue
The issue's rail has a Suspect deploy row: the last deploy to the environment the issue began
in, at or before the moment it was first seen, the release that deploy carried, and the commits
that shipped with it (see above). It says how sure it is: whether the issue's first event carried
that release, and how long the deploy preceded it, so a deploy from last week reads as the
coincidence it probably is. It is a pointer to where to look, not a verdict. When the issue names a
service (a service tag on its first event) only that service's deploys, and deploys that name no
service, are candidates; the answer says basis: service for the service's own deploy and
environment_only when no service was matched, so a deploy of another service is never presented
as certain. A deploy that failed is never the suspect. The row is absent for
a project that records no deploys. GET …/issues/{id}/suspect-deploy returns the same.
Release health by OS, browser, device and environment
The release page has a Health by segment panel: the release's sessions grouped by
operating system, browser, device class (desktop, mobile, tablet, bot, other) or
environment, each row with its sessions, share, crash-free sessions and crash-free users, every
rate beside its denominator. The same grouping is GET …/release-health/{version}?groupBy=os|browser|device|environment
(a segments object on the usual response), and the crash-free rate dashboard widget takes a
Break down by setting that adds the same rows.
- Where the dimensions come from. A session item's
attrs.user_agent. The browser SDK sendsnavigator.userAgent; the server reads the OS, browser family and device class from it when the session arrives and does not keep the string. Versions are not kept either: "Chrome 124.0.6367.91" is thousands of groups of one, and a group of one is not a crash-free rate. Sentry's browser SDKs sendattrs.user_agenttoo, so they segment with no change. - Unknown is a row. A session that sent no User-Agent (an older SDK, a runtime that is not a browser) and every session recorded before this existed is Unknown, so the rows always add up to the release's sessions and you can see how much of it was measurable. There is no backfill.
- Aggregate sessions have no device. A Sentry server SDK in request mode sends counts per
minute (
sessionsitems, stored inrelease_session_aggregates), not sessions, so there is no User-Agent or device behind them. They are in the release's totals and in the environment grouping (which they do carry), and in no OS, browser or device row. The panel and the API (excludedAggregatedSessions) say how many, rather than guessing a split. - iPad. iPadOS 13+ identifies itself as a Mac and is counted as one: nothing in the User-Agent tells them apart.
What changed: the change stream
Deploys are one kind of change. A rollback, a feature flag flipped, an alert rule edited and a
bucker.yml applied are others, and "what changed before this broke" is the first thing anyone
asks. Bucker keeps them in one stream and shows it in four places: a Changes around this release
panel on every release page (six hours before the release's latest deploy to a day after it), flag
and configuration markers on time axes that belong to one project (the replay in the alert rule
editor says what changed just before the latest fire), GET …/change-events for your own tools,
and the change_events_list MCP tool for your agents.
# The latest changes, newest first (project:read).
curl -H "Authorization: Bearer $BUCKER_TOKEN" \
"https://api.bucker.io/orgs/acme/projects/web/change-events?kind=DEPLOY,ROLLBACK&environment=production&limit=25"
# Record a marker of your own: a freeze, a cache flush, a migration window (release:write).
curl -X POST -H "Authorization: Bearer $BUCKER_TOKEN" -H "Content-Type: application/json" \
"https://api.bucker.io/orgs/acme/projects/web/change-events" \
-d '{"summary": "Holiday feature freeze started", "environment": "production"}'
- Filters.
kind(comma-separated:DEPLOY,ROLLBACK,FLAG_FLIP,CONFIG, and the rest of the closed list),service,environment,configSubject,entityId,fromandto, andhasOperation=true|falseto split the configuration changes a governed operation applied (they carry anoperationId) from the rest.limitis 1 to 100, andnextCursorpages with no row skipped or repeated, including rows that share a millisecond. - Corrections show the latest. A row can name the row it replaces (
supersedesId). The list leaves the replaced row out unless you passincludeSuperseded=true, and says how many it left out (supersededHidden). It is decided across the whole project, so a correction recorded after the end of your range still hides what it corrected. - Every row says who and how far to trust it.
actorKindandactorMode(a person, an agent, Bucker itself or an outside system), andtrust:untrustedmarks a row built from third-party text. A deploy row carries the deploy's current outcome (deployStatus). - What a bucker.yml apply leaves. One
CONFIGrow per changed resource, per project it touched, grouped by oneoperationId; an MCP configuration write leaves one carrying the plan digest. Both are written after the change landed and cannot fail it. - Your own markers are narrow on purpose.
POST …/change-eventswrites oneCONFIGrow with the subjectcustom, as the credential that made the call. The body accepts a summary (up to 500 characters),service,environment,entityId,reference,occurredAtandsupersedesId; anything else, including a different kind, an actor, a trust level or an operation id, is a 400. It is append-only (no edit, no delete), at most sixty a minute per credential, andsupersedesIdmay only name a custom marker of the same project, so a deploy cannot be hidden from a chart by a CI token. It has no MCP tool.
Sending deploys to PagerDuty
Turn on Change Events in a PagerDuty integration's settings ("changeEvents": true) and Bucker
posts that organization's deploys, rollbacks and operation applies to PagerDuty's Change Events
API with the integration's routing key, so they appear on the incident timeline. It is off unless
you set it. Use a routing key from a Change Events integration in PagerDuty; an alerts-only key
is refused (a 4xx), and the refusal appears in the delivery record rather than being retried.
- What leaves. The summary (scrubbed for credentials and keys), the time, the source, and the kind, project, environment, service, reference, configuration subject and operation id. No names, no approval ids, no metadata. Fleet-wide markers, flag flips, plain configuration changes and your own markers are never sent.
- Delivery record. One audit row per attempt (
integration.change_event.delivery): delivered rows are never sent again, a transient failure is retried up to three times, and a permanent refusal (400, 401, 402, 403) is not retried. PagerDuty's answer is not stored. - Your network policy still applies. If your organization enforces an egress allow-list, the PagerDuty host must be on it, or the delivery fails and says so.
See also Application performance for release verdicts, and CI, gates and flaky tests for the gate rule that reads release health.