
release-tools
Release workflow tools - auto-versioning, release notes, changelog updates
- GitHub stars
- 497
Install
/plugin install release-tools@umputun-cc-thingzRun it inside Claude Code after adding the marketplace with /plugin marketplace add umputun/cc-thingz.
Contents
Discovered from sourceSkills 2
Last Tag - Commits Since Last Release
Show commits since the last tag in a formatted table with optional details.
Activation Triggers
- "last tag", "last-tag", "since last tag"
- "what changed since last release"
- "commits since last tag"
- "what's new", "unreleased changes"
Workflow
Important: Avoid $() command substitution in Bash tool - use sequential steps.
- Fetch tags from remote and get the last tag:
git fetch origin --tags
Then get the last tag:
git describe --tags --abbrev=0
Store this value (e.g., v1.2.3) for use in subsequent commands.
- Get commits since that tag with format
date|author|hash|subject(substitute TAG with actual value):
git log TAG..HEAD --format="%ad|%an|%h|%s" --date=short
-
Check if all commits have the same author - extract unique authors from step 2 output. If only one unique author name appears in all rows, it's a single author.
-
Format output:
If single author (count = 1):
Last tag: v1.2.3
Author: John Doe
| Date | Commit | Description |
|------------|---------|--------------------------------|
| 2025-12-20 | abc1234 | fix: resolve null pointer |
| 2025-12-19 | def5678 | feat: add user authentication |
If multiple authors (count > 1):
Last tag: v1.2.3
| Date | Author | Commit | Description |
|------------|----------|---------|--------------------------------|
| 2025-12-20 | John Doe | abc1234 | fix: resolve null pointer |
| 2025-12-19 | Jane Doe | def5678 | feat: add user authentication |
If no tag exists:
No tags found in repository
If no commits since tag:
Last tag: v1.2.3
No commits since this tag
Interactive Details
After displaying the table, use AskUserQuestion:
question: "Show commit details?"
header: "Details"
options:
- label: "All commits"
description: "Show full details for each commit"
- label: "None"
description: "Skip details"
- label: "Specific commit"
description: "Enter commit hash to inspect"
If "All commits": For each commit, run:
git show --stat --format="Commit: %h%nAuthor: %an <%ae>%nDate: %ad%n%n%s%n%n%b" --date=short HASH
This shows: commit hash, author with email, date, subject, body, and file change stats.
If "None": End.
If "Specific commit" or user enters hash via "Other": Run the same git show command for that commit only.
Release Workflow
Creates GitHub, GitLab, or Gitea releases with auto-versioning and release notes generation.
Activation Triggers
- "create release", "cut release", "new release"
- "publish version", "bump version", "new version"
- "tag and release"
Scripts
Helper scripts in skill's scripts/ directory (use ${CLAUDE_PLUGIN_ROOT} for path resolution):
detect-platform.sh- outputsgithub,gitlab, orgiteacalc-version.sh <type>- outputs new version (e.g.,v1.2.3)get-notes.sh <platform>- outputs release notes (PRs/MRs or commits)
Every helper exits non-zero and prints the reason on stderr. If any of Steps 2, 5 or 6
fails, report that text to the user and abort the workflow - do not continue with an
empty value. get-notes.sh in particular fails when the forge CLI is missing,
unauthenticated or rate-limited; continuing there publishes a release whose notes list
none of its PRs.
On Gitea, get-notes.sh collects no PRs and returns commit-derived notes with a warning
on stderr, because tea pr list exposes neither a merged flag nor a merge timestamp. That warning
is not a failure - show it to the user with the preview in Step 8 and carry on.
Workflow
Step 1: Ask Release Type
Use AskUserQuestion tool to get release type:
{
"questions": [{
"question": "What type of release is this?",
"header": "Version",
"options": [
{"label": "Hotfix", "description": "Bug fixes (1.2.3 → 1.2.4)"},
{"label": "Minor", "description": "New features (1.2.3 → 1.3.0)"},
{"label": "Major", "description": "Breaking changes (1.2.3 → 2.0.0)"}
],
"multiSelect": false
}]
}
Step 2: Detect Platform
platform=$(bash ${CLAUDE_PLUGIN_ROOT}/skills/new/scripts/detect-platform.sh)
Step 3: Validate Prerequisites
# working tree must be clean
if [ -n "$(git status --porcelain)" ]; then
echo "error: uncommitted changes - commit or stash first"
fi
# sync with remote (--tags ensures all remote tags are fetched)
git fetch origin --tags
Step 4: Get Current Version
last_tag=$(git describe --tags --abbrev=0 --match "v*" 2>/dev/null || echo "none")
Step 5: Calculate New Version
new_version=$(bash ${CLAUDE_PLUGIN_ROOT}/skills/new/scripts/calc-version.sh <release_type>)
Verify tag doesn't already exist:
if git rev-parse "$new_version" &>/dev/null; then
echo "error: tag $new_version already exists"
fi
Step 6: Generate Release Notes
notes=$(bash ${CLAUDE_PLUGIN_ROOT}/skills/new/scripts/get-notes.sh "$platform")
Script logic:
- Collects PRs/MRs merged after last tag (with author)
- Collects commits since last tag (with hash)
- Categorizes by conventional commit prefix (feat/fix/refactor/etc.)
- Groups into: New Features, Improvements, Bug Fixes, Other
- Strips prefix from description for cleaner output
Post-processing (Claude must do this before presenting):
- Deduplicate entries with same description (PRs and their commits often duplicate)
- Prefer PR entries over commit entries when duplicated (PR has #number and @author)
- Compare descriptions after stripping conventional prefix
Output format:
**New Features**
- add user authentication #45 @username
- implement caching d41d3ad
**Improvements**
- refactor auth module abc1234
- update dependencies #47 @contributor
**Bug Fixes**
- resolve login timeout #46 @username
- handle nil pointer def5678
Step 7: Check and Update CHANGELOG
# detect actual changelog filename (case-sensitive filesystem!)
changelog=""
for f in CHANGELOG.md changelog.md CHANGELOG; do
[ -f "$f" ] && changelog="$f" && break
done
If changelog exists:
- CRITICAL: Use the exact detected filename (
$changelog) for all operations - do not hardcode "CHANGELOG.md" - Read the file to understand its format (Keep a Changelog, simple list, etc.)
- Add new version section at the top (after any header/intro)
- Use the generated release notes
- Match the existing format and style
- Commit the changelog update using the detected filename:
git add "$changelog"
git commit -m "docs: update changelog for $new_version"
Common formats to detect:
- Keep a Changelog: Has
## [Unreleased]section, versions as## [X.Y.Z] - YYYY-MM-DD - Simple list: Just version headers like
## X.Y.Zor# X.Y.Z - Date-based: Versions with dates in various formats
Step 8: Preview and Confirm
Show the release preview to user:
=== Release Preview ===
Platform: GitHub/GitLab
Current version: v1.2.3
New version: v1.3.0
Title: Version 1.3.0
CHANGELOG: <detected filename> will be updated (or "none found")
Release Notes:
--------------
**New Features**
- add user authentication #45 @username
**Improvements**
- refactor auth module abc1234
**Bug Fixes**
- resolve login timeout #46 @contributor
--------------
Use AskUserQuestion tool to confirm:
{
"questions": [{
"question": "Proceed with creating this release?",
"header": "Release",
"options": [
{"label": "Yes, publish", "description": "Create tag and publish release"},
{"label": "Cancel", "description": "Abort release"}
],
"multiSelect": false
}]
}
Wait for user confirmation before creating release.
Step 9: Create Release
Only after user confirms:
Create an annotated tag locally and push it before calling the forge. Forge release commands create lightweight tags when the tag is absent; a lightweight tag has no release time of its own, so the next release would use the target commit's older committer date as its PR cutoff and re-list already released PRs.
git tag -a "$new_version" -m "Version ${new_version#v}"
git push origin "$new_version"
If either command fails, report the error and abort before creating the release. If the forge release command below fails after the push, report that the annotated tag already exists remotely and retry only that release command after the problem is resolved. Do not recreate or delete the tag.
GitHub:
gh release create "$new_version" \
--title "Version ${new_version#v}" \
--notes "$notes"
GitLab:
glab release create "$new_version" \
--name "Version ${new_version#v}" \
--notes "$notes"
Gitea:
tea release create \
--tag "$new_version" \
--title "Version ${new_version#v}" \
--note "$notes"
Step 10: Report Result
After successful creation:
- Show new version
- Show release URL
- Confirm release was published
Edge Cases
| Case | Handling |
|---|---|
| No previous tags | Default version based on type |
| Pre-release tag (v1.2.3-rc1) | Strip suffix, use base version |
| No PRs/MRs found | Show commits only (still with hashes) |
| Tag already exists | Error and abort |
| No CHANGELOG file | Skip changelog update |
| Unknown CHANGELOG format | Ask user or use simple ## vX.Y.Z format |
Notes
- Tag format:
vX.Y.Z - Title format:
Version X.Y.Z - Entry format:
- description #123 @author(PRs) or- description abc1234(commits) - PRs use
#123(GitHub/Gitea) or!123(GitLab) - Grouped by type: New Features (feat), Improvements (refactor/perf/chore/docs), Bug Fixes (fix), Other
- Conventional commit prefix stripped from description for cleaner output
- Always show preview and get confirmation before publishing
Sponsors
Details
- Marketplace
- umputun/cc-thingz
- Source
- plugins/release-tools
- Category
- Community