Autoship

Automated Releases with autoship

Core Workflow

Every release follows this pattern:

1. Configure: autoship add <name> (one-time setup) 2. Release: autoship <name> (interactive) or autoship <name> -t patch -y (automated)

The tool handles the complete release cycle:

• Clone repository
• Analyze changes and suggest release type (patch/minor/major)
• Generate AI-powered changeset description
• Create and merge changeset PR
• Wait for and merge Version Packages PR
• Trigger npm publish

Requirements

Before using autoship, ensure:

# GitHub CLI must be authenticated
gh auth login

# API key for AI features
export AI_GATEWAY_API_KEY="your-key"

Essential Commands

# One-time setup: add a repository
autoship add myproject
# Prompts for: owner, repo name, base branch

# List configured repositories
autoship list

# Interactive release (prompts for type and message)
autoship myproject

# Automated release (no prompts)
autoship myproject -t patch -y
autoship myproject -t minor -y
autoship myproject -t major -y

# Release with custom message (skips AI generation)
autoship myproject -t patch -m "Fixed login bug" -y

Command Options

autoship [repo]                    # Interactive repo selection if omitted
  -t, --type <type>                # Release type: patch, minor, major
  -m, --message <message>          # Custom changeset description
  -y, --yes                        # Skip all confirmations
  -h, --help                       # Show help

Common Patterns

Fully Automated Patch Release

autoship myproject -t patch -y

AI-Assisted Interactive Release

autoship myproject
# 1. AI analyzes commits since last release
# 2. AI suggests release type (patch/minor/major)
# 3. You confirm or change the type
# 4. AI generates changeset description
# 5. You review and approve
# 6. Tool handles PR creation and merging

Custom Message Release

autoship myproject -t minor -m "Added new authentication providers" -y

CI/CD Integration

# In GitHub Actions or CI pipeline
export AI_GATEWAY_API_KEY="${{ secrets.AI_GATEWAY_API_KEY }}"
npx autoship myproject -t patch -y

What autoship Does (10 Steps)

1. Clone - Clones the repository from the base branch 2. Analyze - Finds latest version tag, analyzes commits and diff 3. Suggest - AI suggests release type based on changes 4. Generate - AI generates changeset description 5. Branch - Creates release branch with changeset file 6. PR - Creates pull request for the changeset 7. Wait - Waits for CI checks to pass 8. Merge - Merges the changeset PR 9. Version PR - Waits for changesets action to create Version Packages PR 10. Publish - Merges Version Packages PR to trigger npm publish

Output Format

autoship provides clear step-by-step output:

[1/10] Cloning repository from main...
  > Repository cloned
  > Package: my-package @ 1.2.3

[2/10] Creating release branch...
  > Branch created: release/patch-1706123456789

[3/10] Generating changeset...
  > Changeset created: fluffy-pants-dance.md

...

Release Complete!
The patch release has been published.

Configuration

Config is stored at ~/.autoship/config.json:

{
  "repos": {
    "myproject": {
      "owner": "vercel-labs",
      "repo": "myproject",
      "baseBranch": "main",
      "cloneUrl": "https://github.com/vercel-labs/myproject.git"
    }
  }
}

Deep-Dive Documentation

Ready-to-Use Templates

./templates/automated-release.sh myproject patch
./templates/setup-repo.sh myproject vercel-labs myproject main

Troubleshooting

"No repositories configured"

Run autoship add <name> to configure a repository first.

"Repository not found"

Check autoship list for available repos. The name is case-sensitive.

CI checks failing

The tool will show which checks failed. Fix the issues in the target repository, then retry.

AI generation failed

If AI fails, autoship falls back to manual input. Ensure AI_GATEWAY_API_KEY is set.

CI/CD Integration

Run autoship in CI/CD pipelines for fully automated releases.

GitHub Actions

Scheduled Releases

Release on a schedule (e.g., weekly):

name: Scheduled Release

on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9am UTC
  workflow_dispatch:
    inputs:
      repo:
        description: 'Repository to release'
        required: true
        type: string
      type:
        description: 'Release type'
        required: true
        type: choice
        options:
          - patch
          - minor
          - major

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: pnpm/action-setup@v2
      
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      
      - name: Install autoship
        run: pnpm add -g autoship
      
      - name: Configure repository
        run: |
          mkdir -p ~/.autoship
          echo '${{ secrets.AUTOSHIP_CONFIG }}' > ~/.autoship/config.json
      
      - name: Run release
        env:
          AI_GATEWAY_API_KEY: ${{ secrets.AI_GATEWAY_API_KEY }}
          GH_TOKEN: ${{ secrets.GH_TOKEN }}
        run: |
          autoship ${{ inputs.repo || 'myproject' }} \
            -t ${{ inputs.type || 'patch' }} \
            -y

Trigger on Label

Release when a PR is labeled:

name: Release on Label

on:
  pull_request:
    types: [labeled]

jobs:
  release:
    if: contains(github.event.label.name, 'release:')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: pnpm/action-setup@v2
      
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      
      - name: Determine release type
        id: type
        run: |
          LABEL="${{ github.event.label.name }}"
          if [[ "$LABEL" == "release:major" ]]; then
            echo "type=major" >> $GITHUB_OUTPUT
          elif [[ "$LABEL" == "release:minor" ]]; then
            echo "type=minor" >> $GITHUB_OUTPUT
          else
            echo "type=patch" >> $GITHUB_OUTPUT
          fi
      
      - name: Install and run autoship
        env:
          AI_GATEWAY_API_KEY: ${{ secrets.AI_GATEWAY_API_KEY }}
          GH_TOKEN: ${{ secrets.GH_TOKEN }}
        run: |
          pnpm add -g autoship
          mkdir -p ~/.autoship
          echo '${{ secrets.AUTOSHIP_CONFIG }}' > ~/.autoship/config.json
          autoship myproject -t ${{ steps.type.outputs.type }} -y

Environment Variables

Set these secrets in your CI environment:

Creating AUTOSHIP_CONFIG Secret

# Copy your local config to clipboard
cat ~/.autoship/config.json | pbcopy  # macOS
cat ~/.autoship/config.json | xclip   # Linux

# Add as secret in GitHub repo settings

Best Practices

1. Use Workflow Dispatch for Manual Triggers

Always include workflow_dispatch for manual triggering:

on:
  workflow_dispatch:
    inputs:
      type:
        description: 'Release type'
        required: true
        type: choice
        options: [patch, minor, major]

2. Pin autoship Version

For reproducible builds, pin the version:

- run: pnpm add -g autoship@1.0.0

3. Validate Before Release

Add a validation step:

- name: Validate
  run: |
    # Ensure we have changes to release
    if git diff --quiet HEAD $(git describe --tags --abbrev=0); then
      echo "No changes since last release"
      exit 0
    fi

4. Notify on Completion

- name: Notify
  if: success()
  run: |
    curl -X POST "${{ secrets.SLACK_WEBHOOK }}" \
      -H "Content-Type: application/json" \
      -d '{"text": "Released ${{ inputs.repo }} (${{ inputs.type }})"}'

Troubleshooting CI

"gh: command not found"

Install GitHub CLI in your workflow:

- name: Install GitHub CLI
  run: |
    curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
    sudo apt update
    sudo apt install gh

Or use the official action:

- uses: cli/cli-action@v1

"Authentication required"

Ensure GH_TOKEN is set and has sufficient permissions:

env:
  GH_TOKEN: ${{ secrets.GH_TOKEN }}

The token needs repo scope for private repositories.

Command Reference

Complete reference for all autoship commands. For quick start and common patterns, see SKILL.md.

Main Command

autoship [repo] [options]

If repo is omitted, displays an interactive selector with all configured repositories.

Options

Examples

# Interactive mode - prompts for everything
autoship myproject

# Specify release type, AI generates message
autoship myproject -t minor

# Fully automated with custom message
autoship myproject -t patch -m "Fixed login validation" -y

# Fully automated with AI message
autoship myproject -t patch -y

add Command

Add a new repository configuration.

autoship add <name>

Arguments

Interactive Prompts

1. GitHub owner - Organization or username (required) 2. Repository name - GitHub repository name (defaults to name) 3. Base branch - Branch to release from (defaults to main)

Example

autoship add myproject
# > GitHub owner (org or user): vercel-labs
# > Repository name: myproject
# > Base branch: main
# Repository "myproject" added!
# Clone URL: https://github.com/vercel-labs/myproject.git

list Command

List all configured repositories.

autoship list

Output

Configured repositories:
  - myproject (vercel-labs/myproject)
  - another-lib (vercel-labs/another-lib)

Environment Variables

Exit Codes

Common error scenarios:

• Repository not configured
• GitHub CLI not authenticated
• CI checks failed
• AI API unavailable (falls back to manual input)

Configuration Reference

autoship stores configuration in ~/.autoship/config.json.

Config File Structure

{
  "repos": {
    "<name>": {
      "owner": "<github-owner>",
      "repo": "<github-repo>",
      "baseBranch": "<branch>",
      "cloneUrl": "<clone-url>"
    }
  }
}

Repository Configuration

Fields

Example

{
  "repos": {
    "ai-sdk": {
      "owner": "vercel",
      "repo": "ai",
      "baseBranch": "main",
      "cloneUrl": "https://github.com/vercel/ai.git"
    },
    "agent-browser": {
      "owner": "vercel-labs",
      "repo": "agent-browser",
      "baseBranch": "main",
      "cloneUrl": "https://github.com/vercel-labs/agent-browser.git"
    }
  }
}

Managing Configuration

Add Repository (Recommended)

Use the CLI to add repositories:

autoship add myproject

This interactively prompts for all required fields.

Manual Editing

You can also edit ~/.autoship/config.json directly:

# Open config file
$EDITOR ~/.autoship/config.json

Remove Repository

Currently, remove repositories by editing the config file directly:

# Edit and remove the entry from "repos"
$EDITOR ~/.autoship/config.json

Requirements for Target Repositories

autoship works with repositories that use the changesets workflow:

1. Changesets installed - @changesets/cli as dev dependency 2. Changesets config - .changeset/config.json exists 3. Changesets GitHub Action - Configured to create Version Packages PRs 4. Version tags - Repository uses version tags (e.g., v1.2.3, package@1.2.3)

Typical Target Repository Setup

# In the target repository
pnpm add -D @changesets/cli
npx changeset init

.github/workflows/release.yml:

name: Release

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install
      - uses: changesets/action@v1
        with:
          publish: pnpm release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}