| name | ship-release-skill |
| description | Ship a release branch by publishing a GitHub release using the gh CLI. Parses version from self.versions.toml and gets release notes from docs/CHANGELOG.md. |
Ship Release Branch Skill
Overview
This skill guides the agent in shipping a release branch by creating and publishing a GitHub release pointing to the tip of the release branch. It ensures consistency by:
- Resolving the release version directly from
self.versions.toml on the target release branch (never assuming the branch name matches the version name, as hotfixes are appended to existing release branches).
- Extracting release notes from the corresponding section in
docs/CHANGELOG.md.
- Publishing the GitHub release using the
gh CLI with matching tag name and release name (format: v<VERSION>).
Dependencies
release-branch-skill: Typically run after a release branch is cut and hardened.
Prerequisites
- Merge PRs via GitHub: Ensure the version bump PR (and any hardening PRs) are merged via the GitHub UI or
gh pr merge. NEVER use local merge commits on the release branch.
- Pull Latest: Once PRs are merged on GitHub, checkout the release branch locally and pull the latest changes from
origin to ensure the local branch is up-to-date before starting the release process.
- Verify Version: The version in
self.versions.toml must NOT end with -SNAPSHOT. If it does, the release process must be aborted until the version is properly bumped.
Quick Start
To perform a dry-run and verify release notes/version before shipping:
./scripts/ship-release.py --dry-run --output /tmp/release-dry-run.json
To ship the current release branch:
./scripts/ship-release.py --output /tmp/release-result.json
Utility Scripts
The skill uses the ./scripts/ship-release.py script.
Arguments
--branch <branch>: Target branch/ref to point the release to (defaults to current branch).--dry-run: Prints release details and the gh command without executing them.--output <file_path>: (Required) Path to write a JSON report of the release results.
Example JSON output (/tmp/release-result.json):
{
"success": true,
"dry_run": false,
"tag": "v1.1.0",
"title": "v1.1.0",
"branch": "release/v1.1.0",
"url": "https://github.com/episode6/reflective-mockk/releases/tag/v1.1.0",
"notes": "- CI: Use gradle/actions/setup-gradle@v6...\n- Upgraded Kotlin to 2.3.21..."
}
Common Mistakes
- Shipping a Snapshot: Trying to ship when the version in
self.versions.toml still contains -SNAPSHOT. The script will detect this and fail.
- Missing Changelog Section: Forgetting to update
docs/CHANGELOG.md with the release version and date. The script will fail if the section matching v<VERSION> cannot be found.
- Mismatched release notes: Assuming the release notes can be typed manually. Always extract them directly from
docs/CHANGELOG.md using the script to avoid discrepancies.
- Stale Local Branch: Forgetting to pull the latest changes from
origin before shipping, which can lead to releasing an outdated version of the code.
