Dispatch Release
Overview
The Cartridge Controller uses a two-phase release process:
-
Dispatch: Creates a release preparation PR with version bumps
-
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:
jq -r '.version' packages/controller/package.json
Step 2: Dispatch via GitHub CLI
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
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:
-
A PR titled "Prepare release: X.Y.Z" (or "Prepare prerelease: X.Y.Z")
-
A draft GitHub release
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:
gh pr merge <PR_NUMBER> --merge
This triggers release.yml which:
-
Builds all packages
-
Publishes to npm (@cartridge/controller , @cartridge/connector )
-
Finalizes the GitHub release with changelog
Verifying the Release
After merge, verify:
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:
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:
-
Create fix on main (or cherry-pick)
-
Dispatch patch version release
-
Fast-track review and merge
Failed Release
If npm publish fails:
-
Check the release.yml workflow logs
-
Fix the issue
-
Re-run the workflow or manually dispatch release.yml
gh workflow run release.yml
Example: Full Release Flow
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