Releases and release health
Monitor → Releases. A release is a version of your app as the SDKs send it: the Guidely SDKs' appVersion (2.4.1, web@2.4.1, api@2.1.0+abc123, a commit sha…), or release in a Sentry SDK. Per release, in the environment picked in the header:
- Release health: sessions, crash-free sessions and crash-free users, errored and abnormal sessions, median and p90 session duration, with the release before it to compare.
- Adoption: the share of the environment's sessions (and users) in the last 24 hours on the release, and over time on the release page.
- Issues: new in this release, regressed in it (resolved before, seen again), and resolved by it.
- Commits, files changed and authors (sent from CI with the Guidely CLI, or fetched from GitHub), commit authors shown as teammates when their email is a member's.
- Deploys per environment, as dashed markers on the release's chart and on the issue page's occurrences chart.
The list sorts by date, adoption, crash-free sessions, crash-free users or sessions, and searches by version.
Where releases come from
- Events, sessions and transactions: the first one carrying a new version creates the release (and its row in Insights → App versions). Ingest keeps the first and last event per release. Set the version once and every SDK event carries it:
SDK Version Web ( @guidelytech/react,nextjs,svelte,sdk-core)Guidely.init({ …, appVersion: "2.4.1" })/<GuidelyProvider appVersion="2.4.1">Script tag <script … data-app-version="2.4.1">iOS, Android, React Native Sent on its own (the app's version and build); appVersionoverrides itNode, PHP, Java appVersion(Node, PHP),.appVersion("2.4.1")(Java)
- CI, with the Guidely CLI (below):
releases newcreates it before anything is sent,finalizemarks it released,set-commitsattaches commits,deploys newrecords a deploy. - Versions that existed before releases did became releases when the feature was deployed.
The version is stored exactly as sent (trimmed, at most 64 characters), so web@2.4.1 and 2.4.1 are two releases. package@version+build is parsed for display: web@2.4.1+abc shows as 2.4.1 (abc).
Release health
Guidely SDKs
The Guidely SDKs track sessions on their own: once your app sends its appVersion, health comes from its sessions, rolled up every 15 minutes (the last 3 hours are recomputed for late events):
- A session is a Guidely
sessionId, on the app version of its first event, in the hour it started. - Errored: the session has an
exceptionevent. Crashed: one of them was unhandled (uncaught error, unhandled promise rejection or native crash:handlednottrue).captureException()errors and ANRs (mechanism: "anr") count as errored, not crashed. - Duration: first to last event of the session. Users: the session's visitor (identified user, else the anonymous id).
A release with both shows the sessions a Sentry SDK reported (below); the release page says which source it uses.
Sentry SDKs
Sentry SDKs send their own sessions when release is set, and a release that has them shows them:
| SDK | Sessions |
|---|---|
Browser (@sentry/browser, React, Vue…) | One per page load (session items) |
| Mobile (iOS, Android, React Native, Flutter) | One per app foreground (session items), crashes from the native crash handler |
| Node, Python, Ruby, Go… servers | One per incoming request, sent as sessions aggregates |
| Node / Electron processes | Sentry.startSession() / endSession(), or the process session |
How a Sentry session is counted (what the SDK says, as in Sentry):
- Crashed: status
crashed, an unhandled error or native crash ended the session. - Abnormal: status
abnormal, it ended without exiting (app hang, killed by the OS watchdog). - Errored: it reported at least one error (
errors > 0) or endederrored. Errored includes crashed and abnormal sessions. - Healthy: everything else.
Each session counts once, however many updates the SDK sends (Guidely keeps the last state of each session id for 7 days). A user is the session's did (the SDK's user id or device id, stored hashed); a user is crash-free when none of their sessions on the release crashed that day. Sessions without a release are dropped, as Sentry does. Sessions are free: they don't count towards any plan allowance.
Definitions
- Crash-free sessions = 1 − crashed / sessions. Crash-free users = 1 − users with a crash / users. Shown with two decimals and never rounded up to 100% (99.995% shows as 99.99%). Green from 99.5%, amber from 98%.
- Adoption = the release's sessions (users) in the last 24 hours / all sessions (users) of the environment in that time, from the same source. Users are counted per day, so "24 hours" reads today and yesterday for users.
- Session durations are kept as a histogram (31 buckets from 1 s to 24 h); p50 and p90 are interpolated.
Alerts (metric functions)
server/services/release-health-metrics.ts exports crashFreeRate(projectId, environment, { by: "sessions" | "users", release?, from, to }) (0–1, or null without sessions) and sessionCount(...) for alert rules.
Releases from CI
The Guidely CLI (@guidelytech/sourcemaps, the same package that uploads source maps) tells Guidely about each build. Create a key on the Releases page (Create a CI key: a project API key with the releases:write scope) and store it as the CI secret GUIDELY_KEY. Under Environments you can limit the key to some environments: recording a deploy for any other environment (releases deploys … new -e <env>) then gets 403, while creating releases and setting commits work as before. Then, in CI:
export GUIDELY_API_URL=https://guidelytech.com # your Guidely URL
export GUIDELY_KEY=gly_sk_…
VERSION=2.4.1 # the appVersion your app sends
npx @guidelytech/sourcemaps releases new "$VERSION"
npx @guidelytech/sourcemaps releases set-commits "$VERSION" --auto # repository connected: Guidely fetches the commits
# or: … set-commits "$VERSION" --local (commits and changed files from the CI checkout's git history)
# or: … set-commits "$VERSION" --commit "acme/web@<from-sha>..<to-sha>"
npx @guidelytech/sourcemaps releases finalize "$VERSION"
npx @guidelytech/sourcemaps releases deploys "$VERSION" new -e production --name "deploy #$BUILD_NUMBER"
| Command | What it does |
|---|---|
releases new <version> [--project <slug>] [--finalize] | Creates the release (an existing one is left as it is). |
releases set-commits <version> --auto | Matches the checkout's git remote against the workspace's connected repositories and sends HEAD; Guidely fetches the commits since the previous release. |
releases set-commits <version> --local [--initial-depth 20] [--path <dir>] | Sends the commits (with their changed files) since the previous release's newest commit from the local history, or the last --initial-depth commits for a first release or a shallow clone. No repository connection needed. |
releases set-commits <version> --commit <repo>@<from>..<to> | Commit ranges to fetch (repeatable; <repo>@<sha> for "up to this commit"). |
releases set-commits <version> --clear | Removes the release's commits. |
releases finalize <version> | Marks the release released (now). |
releases deploys <version> new -e <env> [--name] [--url] [--time <seconds>] | Records a deploy and sends deploy notifications. |
releases deploys <version> list | Lists its deploys. |
The key finds its workspace and project on its own (GET /api/v1/sourcemaps/whoami); --org / GUIDELY_ORG and --project / GUIDELY_PROJECT are optional checks. GUIDELY_SOURCEMAP_KEY works in place of GUIDELY_KEY; one key can carry releases:write and sourcemaps:write for both jobs. CI checks out shallow clones by default: --local needs the history back to the previous release (e.g. fetch-depth: 0 in GitHub Actions), --auto doesn't.
A key reaches only its own project: the organization in the API paths is the workspace slug, and organization-level calls act on the key's project. Deploys map their environment onto a project environment like events do (prod → production); unknown names file under production and keep the name they were sent with.
Using sentry-cli
Guidely serves the parts of Sentry's web API that sentry-cli uses for releases, so CI that already runs it only changes its variables (same key):
export SENTRY_URL=https://guidelytech.com # your Guidely URL
export SENTRY_ORG=<workspace slug> SENTRY_PROJECT=<project slug>
export SENTRY_AUTH_TOKEN=gly_sk_…
sentry-cli releases new "$VERSION"
sentry-cli releases set-commits "$VERSION" --auto
sentry-cli releases finalize "$VERSION"
sentry-cli releases deploys "$VERSION" new -e production
releases list, releases info, releases delete (refused once events arrived) and releases deploys <version> list work too. The Sentry bundler plugins and @sentry/cli in Node call the same endpoints. Tested with sentry-cli 3.8.
| Endpoint | Used by |
|---|---|
POST/GET /api/0/organizations/{org}/releases/ | releases new, releases list |
GET/PUT/DELETE /api/0/organizations/{org}/releases/{version}/ | info, finalize (dateReleased), set-commits (commits / refs), delete |
GET/POST /api/0/organizations/{org}/releases/{version}/deploys/ | deploys list, deploys new |
GET /api/0/organizations/{org}/releases/{version}/commits/ | the release's commits |
GET /api/0/organizations/{org}/releases/{version}/previous-with-commits/ | set-commits --local (starts after the previous release's last commit) |
GET /api/0/organizations/{org}/repos/ | set-commits --auto (matches the git remote against these URLs) |
GET/POST /api/0/projects/{org}/{project}/releases/, …/releases/{version}/ | releases list and older sentry-cli versions |
The Guidely CLI calls the same organization endpoints.
GitHub
Integrations → GitHub (workspace admins). One connection per workspace, set up as Connect GitHub describes:
- Create the Guidely GitHub App (recommended): Guidely creates a GitHub App for your workspace in your GitHub organization, private to it, and you install it on all or selected repositories. Guidely uses short-lived installation tokens, the repositories follow what you grant on GitHub, and pushed commits arrive as they land. How it works and what it may access: Integrations → GitHub App.
- Or Use a personal access token instead (GitHub Enterprise Server, or no app): a fine-grained personal access token, ideally for a bot account, with Contents: read (commits, files, blame) and Issues: read and write (GitHub Issues); classic tokens with
repowork too. Load the repositories it can reach and pick the ones to add. The token is stored encrypted and never shown again; only its last four characters are. - In each project, Link repository and set its path mapping.
A token connection can be switched to the app at any time (Switch to a GitHub App); repositories, path mappings and commits stay. GitHub Enterprise Server: set GITHUB_API_URL to https://<host>/api/v3 (and GITHUB_WEB_URL for links). Only those hosts are ever called.
Commits
set-commits --auto/--commit repo@shasend refs; the worker fetches the commits from GitHub within seconds (compare from the previous release's last commit in that repository, or the last 20 commits for a first release), with the files each changed (the newest 50 commits). The release page shows "Fetching commits…" until then, and the reason if it failed (for example the app was suspended or uninstalled on GitHub).- With the GitHub App, commits pushed to repositories a project links are stored as they land, with the files they changed, so a release only asks GitHub for its range and suspect commits have file data straight away.
Fixes NORTHWIND-42in a pushed commit still resolves the issue only when the commit ships in a release. set-commits --localsends the commits and their files itself; no GitHub connection is needed. Its repository name is the git remote (origin), which is filed under the project's linked repository (or the workspace's only connected one).
Path mapping
Suspect commits and blame need the stack trace's file paths as repository paths. A mapping replaces a stack root prefix with a source root:
| Frames look like | Stack root | Source root | Repository path |
|---|---|---|---|
app:///src/billing.js | app:/// | src/billing.js | |
/srv/app/billing.py | /srv/app/ | backend/ | backend/billing.py |
https://cdn.example.com/assets/app.js (source-mapped to webpack://./src/app.tsx) | packages/web/ | packages/web/src/app.tsx |
URL schemes and hosts, webpack://, ./ and query strings are dropped first; source-mapped frames use the original source. Without a match, paths are compared by their trailing segments.
Suspect commits
On an issue page: the commits of the issue's first release that changed files its latest event's in-app frames pass through, ranked by how many trailing path segments match and how close to the crash the frame is. With GitHub connected, the commit git blame (GitHub GraphQL) gives for the innermost in-app line at the release's ref (else the default branch) is added on top.
Resolving issues from commits
A commit message with a keyword and an issue's id resolves the issue when the commit is attached to a release (set-commits, or the commits fetched for it):
Fix the empty cart crash. Fixes NORTHWIND-42
closes northwind-7, NORTHWIND-8
Keywords: fix, fixes, fixed, close, closes, closed, resolve, resolves, resolved. The id is the project slug upper-cased and the issue's number (shown on the issue as NORTHWIND-42); any project of the workspace can be named. The key of a Linear or Jira ticket opened from an error works too (Fixes ENG-123 resolves the errors linked to ENG-123). The release lists the issue under Resolved in this release; if it occurs again it regresses as usual.
GitHub Issues
Settings → Issue trackers → GitHub Issues (uses the GitHub connection; pick a repository and default labels). From an error, recording, conversation or complaint, Create ticket opens a GitHub issue with a link back to Guidely and the stack trace, with editable labels, or Link existing issue (#12, owner/repo#12 or the issue URL). Error alert rules can open GitHub issues like Linear and Jira tickets. With the GitHub App, an issue closed or reopened on GitHub shows on its ticket and in the error's activity, and an issue closed as completed resolves the error in the next release (issues).
Deploy notifications
Releases → Deploy notifications: a Slack channel of the project (Integrations → Slack) and email addresses, for the environments you pick (production by default). Each deploy recorded from CI (releases deploys … new) posts the release, its commit count, authors and newest commits, with a link to the release.
Code map
apps/web/src/server/services/releases.ts: releases, ingest hooks, commits, resolution by commit, deploys.apps/web/src/server/services/release-health.ts: session ingest, the Guidely rollup, health queries;release-health-metrics.tsfor alerts.apps/web/src/server/services/release-reports.ts: the Releases pages.release-notify.ts: deploy notifications.apps/web/src/server/services/github.ts(client),repositories.ts(connection, repositories, path mappings, commit fetching),github-app/(each workspace's GitHub App: creation from a manifest, install flow, tokens, webhooks),suspect-commits.ts; GitHub Issues intickets.ts.apps/web/src/server/sentry/handlers/session.ts,apps/web/src/server/sentry/releases-api.tsandapps/web/src/app/api/0/(the release API the Guidely CLI and sentry-cli call); the CLI ispackages/sourcemaps/src/releases.ts.- Tables:
Release,ReleaseDeploy,ReleaseIssue,ReleaseResolution,ReleaseHealthHour,ReleaseHealthUser,ReleaseSessionState,ReleaseHealthRollup,ReleaseSettings,RepositoryConnection,GitHubApp,GitHubAppInstallation,GitHubAppInstallRequest,Repository,ProjectRepository,Commit,CommitFileChange,ReleaseCommit. - Tests use a local GitHub fake (
apps/web/src/test/github-fake.ts) throughGITHUB_API_URL.