---
name: dispatch-release
description: Dispatch a release using GitHub Actions. Use when asked to create a release, publish to npm, or start the release process.
---

# Dispatch Release

## Overview

The Cartridge Controller uses a two-phase release process:
1. **Dispatch**: Creates a release preparation PR with version bumps
2. **Publish**: Merges PR triggers npm publish and GitHub release

## Release Types

| Type | Tag | Use Case |
|------|-----|----------|
| `latest` | Production | Stable releases for general use |
| `prerelease` | Beta/RC | Testing releases before stable |

## Dispatching a Release

### Step 1: Determine Version

Follow semantic versioning:
- **Major** (1.0.0): Breaking changes
- **Minor** (0.1.0): New features, backward compatible
- **Patch** (0.0.1): Bug fixes, backward compatible

Check current version:
```bash
jq -r '.version' packages/controller/package.json
```

### Step 2: Dispatch via GitHub CLI

```bash
# For a production release
gh workflow run release-dispatch.yml \
  -f version="X.Y.Z" \
  -f tag="latest"

# For a prerelease
gh workflow run release-dispatch.yml \
  -f version="X.Y.Z-beta.1" \
  -f tag="prerelease"
```

### Step 3: Monitor Workflow

```bash
# Watch the workflow run
gh run watch

# Or list recent runs
gh run list --workflow=release-dispatch.yml
```

### Step 4: Review the Release PR

The workflow creates:
1. A PR titled "Prepare release: X.Y.Z" (or "Prepare prerelease: X.Y.Z")
2. A draft GitHub release

```bash
# Find the PR
gh pr list --head prepare-release
# or
gh pr list --head prepare-prerelease

# Review the PR
gh pr view <PR_NUMBER>
```

The changelog will be auto-generated by the `changelog-generation.yml` workflow.

### Step 5: Merge to Publish

Once the release PR is reviewed and approved:

```bash
gh pr merge <PR_NUMBER> --merge
```

This triggers `release.yml` which:
1. Builds all packages
2. Publishes to npm (`@cartridge/controller`, `@cartridge/connector`)
3. Finalizes the GitHub release with changelog

## Verifying the Release

After merge, verify:

```bash
# Check npm
npm view @cartridge/controller version
npm view @cartridge/connector version

# Check GitHub releases
gh release list --limit 5

# View specific release
gh release view v<VERSION>
```

## Workflow Files

| File | Purpose |
|------|---------|
| `release-dispatch.yml` | Initiates release, creates PR and draft release |
| `changelog-generation.yml` | Auto-generates changelog for release PRs |
| `release.yml` | Publishes to npm when release PR merges |

## Common Scenarios

### Cancel a Release

If you need to cancel before merge:
```bash
# Close the PR without merging
gh pr close <PR_NUMBER>

# Delete the draft release
gh release delete v<VERSION> --yes
```

### Hotfix Release

For urgent fixes:
1. Create fix on main (or cherry-pick)
2. Dispatch patch version release
3. Fast-track review and merge

### Failed Release

If npm publish fails:
1. Check the `release.yml` workflow logs
2. Fix the issue
3. Re-run the workflow or manually dispatch `release.yml`

```bash
gh workflow run release.yml
```

## Example: Full Release Flow

```bash
# 1. Check current version
jq -r '.version' packages/controller/package.json
# Output: 0.9.5

# 2. Dispatch next minor version
gh workflow run release-dispatch.yml -f version="0.10.0" -f tag="latest"

# 3. Wait for PR creation
sleep 30
gh pr list --head prepare-release

# 4. Review changelog (auto-generated)
gh pr view --web  # Opens in browser

# 5. After review, merge
gh pr merge --merge

# 6. Verify publication
npm view @cartridge/controller version
# Output: 0.10.0
```

## Required Permissions

- GitHub token with `contents: write` and `pull-requests: write`
- npm token (configured as `NPM_TOKEN` secret)
- `CREATE_PR_TOKEN` secret for PR creation