Skip to content
Craft

Quick Start

Craft releases happen in two steps:

  1. craft prepare creates a release branch, bumps versions, checks or generates the changelog, and pushes the branch. Your CI builds release artifacts from it.
  2. craft publish waits for CI to pass, downloads those artifacts, and publishes them to every configured target, then merges the release branch back.

See Release Workflow for what happens at each step.

Installation

Section titled “Installation”

Install the CLI with one command (macOS, Linux, or Windows x64 via Git Bash):

Terminal window
curl -fsSL https://craft.sentry.dev/install | bash

See Installation for Homebrew, standalone binaries, npm, updates, and shell completion. In GitHub Actions, the Craft Action installs Craft for you.

Craft talks to GitHub for almost everything, so export a GITHUB_TOKEN with repo scope before running it locally. See CLI → GitHub token.

Integrate your project

Section titled “Integrate your project”

  1. Build release branches in CI. Make sure your build workflow runs on release branches:

    on:
      push:
        branches:
          - 'release/**'

  2. Upload build artifacts named after the commit SHA, which is what the default GitHub artifact provider looks for:

    - name: Archive Artifacts
      uses: actions/upload-artifact@v4
      with:
        name: ${{ github.sha }}
        path: |
          ${{ github.workspace }}/*.tgz

  3. Add .craft.yml to the repository root with your targets:

    minVersion: '2.21.0'
    changelog:
      policy: auto
    targets:
      - name: github
      - name: npm

    See the configuration reference for every option.

  4. Set up version bumping. With minVersion: '2.21.0' or later, Craft bumps versions automatically based on your targets. Otherwise, add scripts/bump-version.sh or set a custom preReleaseCommand.

  5. Provide credentials for your targets as environment variables (for example NPM_TOKEN). Each target page lists what it needs.

Ship a release

Section titled “Ship a release”

Let’s release version 1.2.3:

Terminal window
craft prepare 1.2.3

This creates the release/1.2.3 branch, bumps versions, commits the changes, and pushes the branch. CI builds and uploads the artifacts.

Terminal window
craft publish 1.2.3

This finds the release branch, waits for CI to pass, downloads the artifacts, publishes them to your targets (for example GitHub and npm), and merges the branch back into your default branch.

You can let Craft choose the version from your commit history instead:

Terminal window
craft prepare auto   # or major, minor, patch

Or do both steps at once with craft prepare 1.2.3 --publish.

Next steps

Section titled “Next steps”