Release and Versioning

All SDK versions MUST follow semantic versioning (SemVer):

<major>.<minor>.<patch>(-<prerelease>)?(+<build>)?

<major>.<minor>.<patch>(-<prerelease>)?(+<build>)?

Pre-release identifiers

Pre-release identifiers MUST be one of: preview, pre, rc, dev, alpha, beta, unstable, a, b. Arbitrary strings are not accepted — anything unrecognized (like -foo or -canary.0) will be treated as a stable release by the release tooling.

Pre-releases don't receive a latest tag in package registries and are not inserted into the internal release-registry used by Sentry product, docs, and tooling.

Valid examples: 1.0.0-preview, 1.0.0-alpha.0, 1.0.0-beta.1, 1.0.0-rc.20

Python note: Python post-releases use a numeric-only suffix (e.g., 1.0.0-1). Since this doesn't match any pre-release identifier, craft treats them as stable releases.

Build identifiers

Build identifiers are optional and used for platform or architecture variants (e.g., 1.0.0+x86_64). When combined with pre-release identifiers, the pre-release comes first: 1.0.0-rc.1+x86_64.

SDKs MUST use craft for release preparation and publish for release approval. Every SDK repo needs:

• .craft.yml — release configuration
• scripts/bump-version.sh — version bump script invoked by craft
• .github/workflows/release.yml — GitHub Actions workflow to trigger releases

Craft targets and bump-version logic are SDK-specific, but the toolchain is the same everywhere. See the setting up release infrastructure playbook for setup instructions.

Merge target

By default, releases merge to the repository's default branch (usually main). To override this, pass the merge_target input in the release workflow:

- name: Prepare release
  uses: getsentry/craft@v2
  env:
    GITHUB_TOKEN: ${{ steps.token.outputs.token }}
  with:
    version: ${{ github.event.inputs.version }}
    merge_target: ${{ github.event.inputs.merge_target }}

- name: Prepare release
  uses: getsentry/craft@v2
  env:
    GITHUB_TOKEN: ${{ steps.token.outputs.token }}
  with:
    version: ${{ github.event.inputs.version }}
    merge_target: ${{ github.event.inputs.merge_target }}

Add a corresponding merge_target input to the workflow's workflow_dispatch.inputs block. The same input is available in the reusable workflow.

Multiple craft configs

When a repository maintains multiple major versions (e.g., v7 and v8) with diverging publishing targets, it can use the .craft.yml from the merge target branch instead of the default branch. Add craft_config_from_merge_target: true to the craft step:

- name: Prepare release
  uses: getsentry/craft@v2
  with:
    craft_config_from_merge_target: true

- name: Prepare release
  uses: getsentry/craft@v2
  with:
    craft_config_from_merge_target: true

For the publish side, register the branch in the publish.yml workflow in getsentry/publish:

- name: Set target repo checkout branch
  if: |
    fromJSON(steps.inputs.outputs.result).repo == 'sentry-javascript' && fromJSON(steps.inputs.outputs.result).merge_target == 'v7'

- name: Set target repo checkout branch
  if: |
    fromJSON(steps.inputs.outputs.result).repo == 'sentry-javascript' && fromJSON(steps.inputs.outputs.result).merge_target == 'v7'

The registered branches MUST be protected — disable direct pushing and require PR approvals before merging.

Once a release is out, see Post-release monitoring and regression handling for what to watch and how to respond.