Skip to content

getting-started.md

Latest commit

 

History

History
202 lines (146 loc) · 5.85 KB

getting-started.md

File metadata and controls

202 lines (146 loc) · 5.85 KB
Raw

Getting Started

This guide walks through installing ReleaseKit, verifying your setup with a dry run, and wiring it into CI.

Prerequisites

  • Node.js 22+
  • A git repository using Conventional Commits
  • At least one git tag marking a previous release (e.g. v0.0.0), or no tags at all for a first release

1. Install

Install the unified CLI:

npm:

npm install -g @releasekit/release

pnpm:

pnpm add -g @releasekit/release

This provides the releasekit command. Individual tools (releasekit-version, releasekit-notes, releasekit-publish) are also available if you need them independently. See the CLI reference for every command and flag.

2. Create a config file

Run the init command to create a releasekit.config.json with sensible defaults:

releasekit init

Or create it manually. The minimal config for a single-package npm project:

Comments (// and /* … */) and trailing commas are supported. Name the file releasekit.config.jsonc if you want your editor to accept comments without warnings — both filenames are auto-discovered.

{
  "$schema": "https://goosewobbler.github.io/releasekit/schema.json",
  "notes": {
    "changelog": { "mode": "root" }
  },
  "publish": {
    "npm": { "enabled": true }
  }
}

For a scoped package (@scope/name), add "access": "public" — npm defaults scoped packages to restricted:

{
  "publish": {
    "npm": { "enabled": true, "access": "public" }
  }
}

The $schema line enables autocompletion and validation in editors that support JSON Schema.

Monorepo

For a monorepo with packages under packages/, write a changelog per package:

{
  "$schema": "https://goosewobbler.github.io/releasekit/schema.json",
  "notes": {
    "changelog": { "mode": "packages" }
  },
  "publish": {
    "npm": { "enabled": true }
  }
}

3. Dry run

Before making any real changes, preview what ReleaseKit would do:

releasekit release --dry-run

This runs the full pipeline — version analysis, changelog generation, publish simulation — without writing any files, creating git tags, or publishing packages. Check the output to confirm the version bump and changelog entries look correct.

If nothing is detected, make sure:

  • Your commits follow the Conventional Commits format (feat:, fix:, etc.)
  • There is at least one commit since the last git tag

4. First release

When the dry run looks right, run the real thing:

releasekit release

This will:

  1. Bump version in package.json (and Cargo.toml if present)
  2. Generate / update CHANGELOG.md
  3. Create a git commit and tag
  4. Publish to npm
  5. Push to remote
  6. Create a GitHub Release (draft by default)

npm authentication — for a local run you need to be logged in to npm:

npm login

Or set NODE_AUTH_TOKEN in your environment if you prefer token-based auth:

NODE_AUTH_TOKEN=npm_... releasekit release

GitHub Release — set GITHUB_TOKEN in your environment:

GITHUB_TOKEN=ghp_... releasekit release

In CI, both tokens are typically available as secrets or via OIDC — see the CI setup guide for details.

5. Set up CI

The most common setup triggers a release on every push to main. See the CI setup guide for complete GitHub Actions workflows covering:

  • Push-to-main releases
  • Label-based triggers (release only when a PR has a bump:patch/minor/major label)
  • npm OIDC trusted publishing (no NPM_TOKEN secret required)
  • PR preview comments
  • Prerelease workflows

Minimal CI workflow

# .github/workflows/release.yml
name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write
  id-token: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: pnpm
          registry-url: 'https://registry.npmjs.org'
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec releasekit release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Using npm? Drop the pnpm/action-setup step, set cache: npm on setup-node, and replace pnpm install --frozen-lockfile with npm ci and pnpm exec with npx.

If you use the label-based trigger, create the required bump:*, channel:*, and release:skip labels with releasekit labels sync — see Create the labels.

Next steps