Skip to content

fix: Update outdated Craft/Publish playbook #18868

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BYK merged 1 commit into from
Jul 31, 2026
+14 −19
Merged

fix: Update outdated Craft/Publish playbook #18868

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
33 changes: 14 additions & 19 deletions ...-docs/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,33 +29,28 @@ Related resources:

## Steps

#### 1. Create the Initial Tag

A tag **MUST** exist for the first commit of the repository due to a [craft limitation](https://github.com/getsentry/craft/issues/342). You **SHOULD** tag the first commit before any meaningful history so the first changelog includes useful context.

```bash
git tag 0.0.0 "$(git log -1 --reverse --format=%h)"
git push origin --tags
```

#### 2. Set Up CI for Release Branches
#### 1. Set Up CI for Release Branches

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

#### 3. Configure Craft (`.craft.yml`)
#### 2. Configure Craft (`.craft.yml`)

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

```yaml
minVersion: 0.28.1
minVersion: 2.27.1
targets:
- name: pypi
- name: github
```

It is highly recommended for you to enable [automatic versioning](https://craft.sentry.dev/configuration/#versioning) and [automated changelog generation](https://craft.sentry.dev/configuration/#auto-mode).

See the [Craft configuration docs](https://craft.sentry.dev/configuration/) for all available targets and options.

#### 4. Add Version Bump Script (`scripts/bump-version.sh`)
#### 3. Add Version Bump Script - _OPTIONAL_ (`scripts/bump-version.sh`)

See [Automated Version Bumping](https://craft.sentry.dev/configuration/#automatic-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`:

Expand All @@ -68,7 +63,7 @@ sed -i "s/^version =.*/version = $2/" setup.cfg

For a real-world example with multiple version locations, see [sentry-python's bump-version.sh](https://github.com/getsentry/sentry-python/blob/master/scripts/bump-version.sh).

#### 5. Add Release Workflow (`.github/workflows/release.yml`)
#### 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](https://docs.github.com/en/actions/reference/events-that-trigger-workflows).

Expand Down Expand Up @@ -111,17 +106,17 @@ jobs:

For full details on all available options including auto-versioning, changelog preview, merge targets, and multiple Craft configs, see [Craft's GitHub Actions documentation](https://craft.sentry.dev/github-actions/). Repositories outside the `getsentry` org can use the simpler [reusable workflow](https://craft.sentry.dev/github-actions/#option-1-reusable-workflow-recommended) which handles token management automatically via `secrets: inherit`.

#### 6. Set Repository Permissions
#### 5. Set Repository Permissions

You **MUST** give the `engineering` team write access via your repository's settings page: `https://github.com/getsentry/REPONAME_HERE/settings/access`
You **MUST** give the `engineering` team write access via [security-as-code](https://github.com/getsentry/security-as-code/) [like this](https://github.com/getsentry/security-as-code/blob/2da8c01ad34b12539cc345c08896b420eb86049f/rbac/env/prod-github/repo/craft.yml#L5)

#### 7. Create Branch Ruleset
#### 6. Create Branch Ruleset

Download the [default ruleset template](/json/Default_ruleset.json). 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.

#### 8. Cut Your First Release
#### 7. Cut Your First Release

Navigate to the Actions tab, locate the Release workflow, and trigger it. This creates an [issue in `getsentry/publish`](https://github.com/getsentry/publish/issues) which requires an approver to add a label before artifacts are published.
Navigate to the Actions tab, locate the Release workflow, and trigger it. This creates an [issue in `getsentry/publish`](https://github.com/getsentry/publish/issues) 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).

Expand Down
Loading