just-ship-it

Automate changeset-based releases with AI-generated descriptions powered by OpenRouter.

Features

• 🤖 AI-Powered Descriptions: Automatically generate meaningful changeset descriptions using AI
• 🔄 Automated Release Workflow: Create changesets, open PRs, merge, and publish releases automatically
• 🎯 Smart Version Suggestions: AI analyzes your changes to suggest appropriate version bumps (patch/minor/major)
• 🔧 Multi-Repository Support: Configure and manage releases for multiple repositories
• 📦 Monorepo Support: Full support for npm, pnpm, yarn, and bun workspaces with lockstep or selective versioning
• 🎨 Model Selection: Choose from 300+ AI models via OpenRouter
• ✅ CI/CD Integration: Waits for checks to pass before merging PRs
• 🔀 Changeset Compatible: Works with existing changeset-based workflows

Installation

For end users:

# Using bun (recommended)
bun add -g just-ship-it

# Or using npm
npm install -g just-ship-it

For development:

# Clone the repository
git clone https://github.com/mattapperson/just-ship-it
cd just-ship-it

# Install bun if you haven't already
curl -fsSL https://bun.sh/install | bash

# Install dependencies
bun install

# Build
bun run build

# Run tests
bun test

Prerequisites

• Node.js 18+: Required for running the CLI

• Bun (for development only): Fast JavaScript runtime and package manager

  • Install: curl -fsSL https://bun.sh/install | bash
  • Or visit bun.sh for other installation methods
  • Note: End users do NOT need bun installed to use just-ship-it

• GitHub CLI: Must be installed and authenticated

  gh auth login

• OpenRouter API Key: Required for AI features

  • Sign up at openrouter.ai

  • Set your API key as an environment variable:

    export OPENROUTER_API_KEY='your_api_key_here'

Setup

1. Install GitHub CLI

# macOS
brew install gh

# Windows
winget install GitHub.cli

# Linux
# See https://github.com/cli/cli#installation

2. Authenticate with GitHub

gh auth login

3. Get OpenRouter API Key

1. Visit openrouter.ai and create an account
2. Generate an API key from your dashboard
3. Add it to your environment:

# Add to ~/.bashrc, ~/.zshrc, or equivalent
export OPENROUTER_API_KEY='sk-or-v1-...'

4. Add a Repository

just-ship-it add my-project

Follow the prompts to configure:

• GitHub owner (organization or user)
• Repository name
• Base branch (typically main)
• AI model (optional, defaults to anthropic/claude-opus-4.5)

Usage

Interactive Mode

Run without arguments to select a repository and configure the release interactively:

just-ship-it

The CLI will:

1. Show you a list of configured repositories
2. Analyze your changes since the last release
3. Suggest a version bump type (patch/minor/major)
4. Generate an AI-powered changeset description
5. Create a changeset and open a PR
6. Wait for CI checks to pass
7. Merge the PR and publish the release

Automated Mode

Specify all options via flags for CI/CD integration:

just-ship-it my-project --type minor --message "Add new authentication feature" --yes

With Custom Model

Override the default model for a specific release:

just-ship-it my-project --model openai/gpt-4o

Commands

just-ship-it [repo]

Run a release for the specified repository (or select interactively).

Options:

• -t, --type <type>: Release type (patch, minor, or major)
• -m, --message <message>: Release message (overrides AI generation)
• -y, --yes: Skip confirmation prompts
• --model <model>: AI model to use for this release

Example:

just-ship-it my-app --type patch --yes

just-ship-it add <name>

Add a new repository configuration.

Options:

• --model <model>: Default model for this repository
• --monorepo: Configure as monorepo (will prompt for versioning mode)
• --lockstep: Use lockstep versioning (all packages bump together)
• --selective: Use selective versioning (only changed packages bump)

Examples:

# Single package repository
just-ship-it add my-project --model anthropic/claude-opus-4.5

# Monorepo with interactive setup
just-ship-it add my-monorepo --monorepo

# Monorepo with lockstep versioning
just-ship-it add design-system --lockstep

# Monorepo with selective versioning
just-ship-it add platform --selective

just-ship-it list

List all configured repositories.

Example:

just-ship-it list

Model Configuration

You can configure which AI model to use at three levels (in order of precedence):

1. CLI Flag (Highest Priority)

Override for a single release:

just-ship-it my-app --model openai/gpt-4o

2. Environment Variable

Set a default model for all releases:

export OPENROUTER_MODEL='anthropic/claude-opus-4.5'

3. Per-Repository Configuration

Configure during add or update the config file (~/.just-ship-it/config.json):

just-ship-it add my-project --model anthropic/claude-opus-4.5

4. Default

If no model is specified, defaults to anthropic/claude-opus-4.5.

Example Models

OpenRouter provides access to 300+ models. Popular choices include:

• anthropic/claude-opus-4.5 - Best for complex reasoning (default)
• anthropic/claude-sonnet-4.5 - Fast and efficient
• openai/gpt-4o - OpenAI's latest
• openai/o1 - Advanced reasoning
• google/gemini-2.5-pro-002 - Google's flagship model
• meta-llama/llama-3.3-70b - Open source powerhouse
• deepseek/deepseek-r1-distill-llama-70b - Cost-effective reasoning

See openrouter.ai/models for the complete list.

Monorepo Support

just-ship-it provides comprehensive support for monorepos with multiple packages. It automatically detects workspace configurations and provides two versioning strategies:

Supported Workspace Types

• npm workspaces - Detected from package.json with workspaces field
• pnpm workspaces - Detected from pnpm-workspace.yaml
• yarn workspaces - Detected from package.json with workspaces field
• bun workspaces - Detected from package.json with workspaces field and bun.lockb

Versioning Modes

Selective Versioning (Recommended)

Only packages with changes are analyzed and released. Best for monorepos with independent packages.

just-ship-it add my-monorepo --selective

How it works:

1. Detects which packages have changes since the last release
2. AI analyzes each changed package independently
3. You can choose to skip or bump each package individually
4. Only changed packages are included in the changeset

Lockstep Versioning

All packages are bumped together, even if they have no changes. Best for tightly coupled packages that should always be on the same version.

just-ship-it add design-system --lockstep

How it works:

1. All packages in the workspace are included
2. AI suggests a single version bump based on all changes
3. All packages receive the same version bump
4. All packages are included in the changeset

Per-Package AI Analysis

For monorepos, just-ship-it analyzes each package's changes independently:

• Examines commits that touched each package
• Reviews files changed within each package
• Suggests appropriate version bump (patch/minor/major) per package
• Generates a unified changeset description covering all packages

Example Workflows

Selective Release:

# Setup
just-ship-it add platform --selective

# Run release
just-ship-it platform

# The CLI will:
# 1. Show you which packages have changes
# 2. Let you review and adjust version bumps per package
# 3. Generate a multi-package changeset
# 4. Create a PR and handle the release

Lockstep Release:

# Setup
just-ship-it add ui-library --lockstep

# Run release
just-ship-it ui-library

# The CLI will:
# 1. Include all packages in the workspace
# 2. Suggest a single version bump for all
# 3. Generate a multi-package changeset
# 4. Create a PR and handle the release

Configuration

Configuration is stored in ~/.just-ship-it/config.json:

Single Package:

{
  "repos": {
    "my-project": {
      "owner": "myorg",
      "repo": "my-project",
      "baseBranch": "main",
      "cloneUrl": "https://github.com/myorg/my-project.git",
      "model": "anthropic/claude-opus-4.5"
    }
  }
}

Monorepo (Selective):

{
  "repos": {
    "my-monorepo": {
      "owner": "myorg",
      "repo": "my-monorepo",
      "baseBranch": "main",
      "cloneUrl": "https://github.com/myorg/my-monorepo.git",
      "model": "anthropic/claude-opus-4.5",
      "monorepo": {
        "mode": "selective"
      }
    }
  }
}

Monorepo (Lockstep):

{
  "repos": {
    "design-system": {
      "owner": "myorg",
      "repo": "design-system",
      "baseBranch": "main",
      "cloneUrl": "https://github.com/myorg/design-system.git",
      "monorepo": {
        "mode": "lockstep"
      }
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OPENROUTER_API_KEY | Yes | - | Your OpenRouter API key | | OPENROUTER_MODEL | No | anthropic/claude-opus-4.5 | Default AI model to use |

How It Works

1. Clone Repository: Creates a temporary clone of your repository
2. Analyze Changes: Uses git log and git diff to analyze changes since the last release
3. AI Analysis: Sends change context to OpenRouter for analysis
4. Generate Changeset: Creates a changeset file with AI-generated description
5. Create PR: Opens a pull request with the changeset
6. CI Checks: Waits for all GitHub checks to pass
7. Merge & Publish: Merges the PR and publishes the release

Troubleshooting

"OPENROUTER_API_KEY environment variable is required"

Make sure your API key is set:

export OPENROUTER_API_KEY='your_key_here'

"GitHub CLI not authenticated"

Run gh auth login to authenticate with GitHub.

"No repositories configured"

Add a repository with:

just-ship-it add my-project

Credits

Based on autoship v0.2.0 by Vercel Labs, adapted to use OpenRouter for model flexibility and broader AI provider access.

License

Apache-2.0

Repository

https://github.com/openrouterteam/just-ship-it