Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,14 +1,17 @@
---
title: Cutting a Release
spec_id: sdk/playbooks/cutting-a-release
spec_version: 1.0.0
spec_version: 1.1.0
spec_status: candidate
spec_depends_on:
- id: sdk/getting-started/standards/review-ci
version: ">=1.0.0"
- id: sdk/getting-started/standards/coordination-maintenance
version: ">=1.0.0"
spec_changelog:
- version: 1.1.0
date: 2026-03-07
summary: Replace CLI invocation of Craft with GitHub Actions workflow — releases are always triggered through CI
- version: 1.0.0
date: 2026-02-23
summary: Initial playbook — release process with gating criteria and post-release monitoring
Expand All @@ -20,9 +23,9 @@ spec_changelog:

## Overview

This playbook guides SDK maintainers through cutting a release for an SDK repository. It covers release gating criteria verification, running release tooling (Craft), artifact verification, and post-release monitoring. By following these steps, releases will be high quality, properly monitored, and quickly addressed if regressions occur.
This playbook guides SDK maintainers through cutting a release for an SDK repository. It covers release gating criteria verification, triggering the release via GitHub Actions, artifact verification, and post-release monitoring. By following these steps, releases will be high quality, properly monitored, and quickly addressed if regressions occur.

All Sentry SDKs use [Craft](https://github.com/getsentry/craft) for release automation with a two-person approval requirement. The process follows a prepare → publish workflow coordinated through the [getsentry/publish](https://github.com/getsentry/publish) repository.
All Sentry SDKs use [Craft](https://github.com/getsentry/craft) for release automation via GitHub Actions. Releases are **always** triggered through CI — never from a local machine. The process follows a prepare → publish workflow coordinated through the [getsentry/publish](https://github.com/getsentry/publish) repository, with a mandatory two-person approval requirement.

Related resources:
- [Review and CI Standards](/sdk/getting-started/standards/review-ci) — release gating criteria
Expand All @@ -37,51 +40,56 @@ Related resources:
#### 1. Verify release gating criteria

You **MUST** verify all criteria pass ([Release gating criteria](/sdk/getting-started/standards/review-ci#release-gating-criteria)):
- All required CI checks pass on the release branch
- All required CI checks pass on the default branch
- No unresolved `h:` (high) review comments on merged PRs since last release
- Changelog is substantive (not empty or internal-only for a release with user-facing changes)
- No known unresolved regressions

#### 2. Prepare the release
#### 2. Trigger the release workflow

Run the Craft prepare command (command varies by SDK — check your SDK's `CONTRIBUTING.md`):
Navigate to the **Actions** tab of your SDK repository. Find the release workflow (typically named "Release" or "Prepare Release") and click **Run workflow**. Select the default branch and enter the version to release, then click **Run workflow**.

```bash
# Common pattern across SDKs
craft prepare <version>
# Or via GitHub Actions workflow (trigger manually)
```
The version input accepts:
- A specific version string (e.g. `2.5.0`)
- `auto` — Craft determines the next version from commit history (supported by some SDKs — check your `CONTRIBUTING.md`)

This creates a release PR in the [getsentry/publish](https://github.com/getsentry/publish) repository. The PR **MUST** be approved by a second SDK maintainer before proceeding.
The workflow runs [Craft](https://github.com/getsentry/craft) to:
- Bump the version in relevant files via the SDK's `bump-version` script
- Generate or update the changelog
- Create a `release/<version>` branch with a release PR
- Build and upload release artifacts
- Open an issue in [getsentry/publish](https://github.com/getsentry/publish) to track the publishing approval

#### 3. Publish the release
#### 3. Polish the release branch (optional)

Once the publish PR is approved, run the Craft publish command:
While CI runs on the `release/<version>` branch, you **MAY** check out the branch and polish the auto-generated `CHANGELOG` — adding code snippets, grouping related entries, and improving readability for users.

```bash
craft publish <version>
# Or merge the publish PR to trigger automated publishing
```
CI **MUST** be passing on the release branch before publishing proceeds. If CI fails, Craft will not publish the release.

Craft will:
#### 4. Approve and publish the release

Once CI is green on the release branch, notify a second SDK maintainer (or your team lead) to approve. They **MUST** add the `accepted` label to the open issue in [getsentry/publish](https://github.com/getsentry/publish/issues). **You MUST NOT approve your own release.**

Adding the label triggers Craft to publish the release automatically. Craft will:
- Create a Git tag
- Build and publish artifacts to package registries
- Create a GitHub release with changelog
- Publish artifacts to the appropriate package registries
- Create a GitHub release with the changelog
- Close the publish issue on success

#### 4. Verify the release artifact
#### 5. Verify the release artifact

The artifact **MUST** be published and installable. Quick smoke test: install the new version in a clean environment and verify basic functionality.

**Note:** Some SDKs have additional verification steps (example app testing, documentation updates) — check your SDK's release documentation.

#### 5. Post-release monitoring
#### 6. Post-release monitoring

You **MUST** follow post-release monitoring procedures ([Post-release monitoring](/sdk/getting-started/standards/coordination-maintenance#post-release-monitoring)):
- Check SDK crash detection within 24 hours
- Verify dogfooding (Sentry's own products) picks up the new version
- Monitor the issue tracker for regression reports for 48 hours

#### 6. If a critical regression is found
#### 7. If a critical regression is found

Trigger the [Handling a Regression](/sdk/getting-started/playbooks/development/handling-a-regression) process.

Expand All @@ -96,6 +104,7 @@ While the core process above applies to all Sentry SDKs, individual SDKs **MAY**

Common SDK-specific variations include:
- Changelog generation (manual vs. auto-generated)
- Whether `version: auto` is supported
- Example app testing requirements
- Documentation PR requirements
- Registry-specific verification steps
Expand Down
Loading