Craft Quick Start

This guide goes over the minimal setup needed to publish something via publish and craft. This example will use a PyPI package.

The First Release

This guide assumes this thing has never been released before and has no existing tags. If that's not the case feel free to skip this section!

A tag must exist for the "beginning" of the repository due to a limitation -- it is recommended to tag the first commit of the repository before any meaningful history such that the first changelog includes useful context.

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

CI Requirements

First we need to ensure your repository responds to release/** branches and produces an artifact with the right name.

For our example repository that's done using push: branches and an artifact instruction.

Setting Up Craft

.craft.yml

We're just interested in making a GitHub release and a PyPI release so our craft configuration looks like:

minVersion: 0.28.1
targets:
- name: pypi
- name: github

scripts/bump-version.sh

This script will be invoked by craft by default when bumping the version.

Since we're specifying version in setup.cfg this is pretty easy to do with sed (we're ignoring $1 which contains the old version):

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

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

Try the script out (but don't commit the changes):

$ ./scripts/bump-version.sh 0.0.0 1.0.0
+ sed -i 's/^version =.*/version = 1.0.0/' setup.cfg
$ git diff | grep '^[-+]'
--- a/setup.cfg
+++ b/setup.cfg
-version = 0.0.0
+version = 1.0.0
$ git checkout -- .

Nice!

.github/workflows/release.yml

This file is used to trigger the release from the GitHub UI.

You'll notice it uses secrets.GH_RELEASE_PAT -- this should already be available to your repository automatically!

name: Release

on:
  workflow_dispatch:
    inputs:
      version:
        description: Version to release
        required: true
      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:
      - uses: actions/checkout@v3
        with:
          token: ${{ secrets.GH_RELEASE_PAT }}
          fetch-depth: 0
      - name: Prepare release
        uses: getsentry/action-prepare-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GH_RELEASE_PAT }}
        with:
          version: ${{ github.event.inputs.version }}
          force: ${{ github.event.inputs.force }}

Commit + PR

Commit those three files and make a pull request.

Here's an example PR and the follow-up to fix fetch-depth.

Setting Up Permissions

Give the following teams access to your repository:

• engineering -> write
• release-bot -> elevated bot

You can do this self-service via the settings page of your repository: https://github.com/getsentry/REPONAME_HERE/settings/access

Making Your First Release!

Navigate to the actions tab of your repository, locate the release workflow, and create the first release! I used 1.0.0 as the first version.

This will create an issue in publish which you'll need an approver to add a label to.