Setting Up Release Infrastructure

Overview

This playbook guides SDK maintainers through setting up automated release infrastructure for a new SDK repository using Craft. It covers initial tagging, CI configuration, version management, and branch protection rules. By following these steps, the repository will support automated changelog generation, artifact publishing, and controlled releases via GitHub Actions.

Related resources:

• Release Versioning Standard — version format and tooling requirements
• Craft Documentation — release automation tool
• Craft GitHub Actions — workflow configuration options

Steps

1. Set Up CI for Release Branches

The repository's CI MUST respond to release/** branches and produce a named artifact.

2. Configure Craft (.craft.yml)

You MUST create a .craft.yml with targets for your package registry and GitHub releases:

minVersion: 2.27.1
targets:
  - name: pypi
  - name: github

minVersion: 2.27.1
targets:
  - name: pypi
  - name: github

It is highly recommended for you to enable automatic versioning and automated changelog generation.

See the Craft configuration docs for all available targets and options.

3. Add Version Bump Script - OPTIONAL (scripts/bump-version.sh)

See Automated Version Bumping and only add a custom script if you really need to.

Craft invokes this script when bumping the version. The script MUST accept the old version as $1 and the new version as $2:

#!/usr/bin/env bash
set -euxo pipefail

sed -i "s/^version =.*/version = $2/" setup.cfg

#!/usr/bin/env bash
set -euxo pipefail

sed -i "s/^version =.*/version = $2/" setup.cfg

For a real-world example with multiple version locations, see sentry-python's bump-version.sh.

4. Add Release Workflow (.github/workflows/release.yml)

You MUST add a release workflow that triggers releases from the GitHub UI. The workflow SHOULD use vars.SENTRY_RELEASE_BOT_CLIENT_ID and secrets.SENTRY_RELEASE_BOT_PRIVATE_KEY which are available to repositories in the getsentry org automatically. These are needed because GitHub prevents GITHUB_TOKEN from triggering downstream workflows.

name: Release

on:
  workflow_dispatch:
    inputs:
      version:
        description: Version to release
        required: false
      force:
        description: Force a release even when there are release-blockers (optional)
        required: false

jobs:
  release:
    runs-on: ubuntu-latest
    name: "Release a new version"
    steps:
      - name: Get auth token
        id: token
        uses: actions/create-github-app-token@5d869da34e18e7287c1daad50e0b8ea0f506ce69 # v1.11.0
        with:
          app-id: ${{ vars.SENTRY_RELEASE_BOT_CLIENT_ID }}
          private-key: ${{ secrets.SENTRY_RELEASE_BOT_PRIVATE_KEY }}
      - uses: actions/checkout@v6
        with:
          token: ${{ steps.token.outputs.token }}
          fetch-depth: 0
      - name: Prepare release
        uses: getsentry/craft@v2
        env:
          GITHUB_TOKEN: ${{ steps.token.outputs.token }}
        with:
          version: ${{ github.event.inputs.version }}
          force: ${{ github.event.inputs.force }}

name: Release

on:
  workflow_dispatch:
    inputs:
      version:
        description: Version to release
        required: false
      force:
        description: Force a release even when there are release-blockers (optional)
        required: false

jobs:
  release:
    runs-on: ubuntu-latest
    name: "Release a new version"
    steps:
      - name: Get auth token
        id: token
        uses: actions/create-github-app-token@5d869da34e18e7287c1daad50e0b8ea0f506ce69 # v1.11.0
        with:
          app-id: ${{ vars.SENTRY_RELEASE_BOT_CLIENT_ID }}
          private-key: ${{ secrets.SENTRY_RELEASE_BOT_PRIVATE_KEY }}
      - uses: actions/checkout@v6
        with:
          token: ${{ steps.token.outputs.token }}
          fetch-depth: 0
      - name: Prepare release
        uses: getsentry/craft@v2
        env:
          GITHUB_TOKEN: ${{ steps.token.outputs.token }}
        with:
          version: ${{ github.event.inputs.version }}
          force: ${{ github.event.inputs.force }}

For full details on all available options including auto-versioning, changelog preview, merge targets, and multiple Craft configs, see Craft's GitHub Actions documentation. Repositories outside the getsentry org can use the simpler reusable workflow which handles token management automatically via secrets: inherit.

5. Set Repository Permissions

You MUST give the engineering team write access via security-as-code like this

6. Create Branch Ruleset

Download the default ruleset template. You MUST import it at https://github.com/getsentry/REPONAME_HERE/settings/rules via New ruleset > Import a ruleset. You MAY adjust settings but MUST NOT remove the App in the Bypass List.

7. Cut Your First Release

Navigate to the Actions tab, locate the Release workflow, and trigger it. This creates an issue in getsentry/publish which requires a reviewer to add the accepted label before artifacts are published.

For the ongoing release process after setup, see "Cutting a release" (wip).

Referenced Standards

• Version format — SemVer requirements
• Release tooling — Craft and publish setup
• Release gating criteria — Pre-release validation requirements
• Rollback procedures — Emergency release rollback process

Changelog