Craft: Universal Release Tool

Craft is a command line tool that helps automate and pipeline package releases. It enforces a specific workflow for managing release branches, changelogs, and artifact publishing.

📚 Full Documentation

Quick Start

Installation

Download the latest binary release, or install via npm:

npm install -g @sentry/craft

Usage

# Auto-determine version from conventional commits
craft prepare auto

# Or specify a version explicitly
craft prepare 1.2.3

# Publish to all configured targets
craft publish 1.2.3

Features

• Auto Versioning - Automatically determine version bumps from conventional commits
• Multiple Targets - Publish to GitHub, NPM, PyPI, Docker, Crates.io, NuGet, and more
• Changelog Management - Auto-generate changelogs from commits or validate manual entries
• Workspace Support - Handle monorepos with NPM/Yarn workspaces
• CI Integration - Wait for CI to pass, download artifacts, and publish
• GitHub Actions - Built-in actions for release preparation and changelog previews

Configuration

Create a .craft.yml in your project root:

minVersion: '2.0.0'
changelog:
  policy: auto
targets:
  - name: github
  - name: npm
    access: public

See the configuration reference for all options.

Supported Targets

Target	Description
github	GitHub releases and tags
npm	NPM registry (with workspace support)
pypi	Python Package Index
crates	Rust crates.io
nuget	.NET NuGet
docker	Docker registries
brew	Homebrew formulas
gcs	Google Cloud Storage
gh-pages	GitHub Pages
cocoapods	CocoaPods
gem	RubyGems
maven	Maven Central
hex	Elixir Hex
pub-dev	Dart/Flutter pub.dev
aws-lambda-layer	AWS Lambda layers
powershell	PowerShell Gallery

See the targets documentation for configuration details.

GitHub Actions

Craft provides GitHub Actions for automating releases and previewing changelog entries.

Prepare Release Action

Automates the craft prepare workflow in GitHub Actions:

name: Release
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to release (or "auto")'
        required: false

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: getsentry/craft@v2
        with:
          version: ${{ github.event.inputs.version }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Inputs:

Input	Description	Default
version	Version to release (semver, "auto", "major", "minor", "patch")	Uses versioning.policy from config
merge_target	Target branch to merge into	Default branch
force	Force release even with blockers	false
blocker_label	Label that blocks releases	release-blocker
publish_repo	Repository for publish issues. Use "self" to create issues in the source repository itself.	{owner}/publish

Outputs:

Output	Description
version	The resolved version being released
branch	The release branch name
sha	The commit SHA on the release branch
changelog	The changelog for this release

Changelog Preview (Reusable Workflow)

Posts a preview comment on PRs showing how they'll appear in the changelog:

name: Changelog Preview
on:
  pull_request:
    types: [opened, synchronize, reopened, edited, labeled]

jobs:
  changelog-preview:
    uses: getsentry/craft/.github/workflows/changelog-preview.yml@v2
    secrets: inherit

The workflow will:

• Generate the upcoming changelog including the PR's changes
• Highlight entries from the PR using blockquote style (left border)
• Post a comment on the PR with the preview
• Automatically update when you update the PR (push, edit title/description, or change labels)

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT