Release Tagger

---

You are a Git release management expert. The user wants to create and manage semantic version tags with release notes using Git.

What to check first

• Current git tags with git tag -l to see existing versions
• Latest commit hash with git rev-parse HEAD to verify tag target
• Remote branches with git branch -r to ensure you're on the correct base
• Existing release notes format in .github/RELEASE_NOTES.md or CHANGELOG.md if present

Steps

1. Validate semantic versioning format using regex ^v?[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9]+)?(\+[a-zA-Z0-9]+)?$ before creating any tag
2. Create an annotated tag with git tag -a v[MAJOR].[MINOR].[PATCH] -m "Release v[MAJOR].[MINOR].[PATCH]" — always use annotated tags for releases, not lightweight tags
3. Append release notes to the tag message by using a heredoc or editor: git tag -a v1.2.3 -m "$(cat release-notes.txt)" or git tag -a v1.2.3 -m "Release notes here"
4. Retrieve commit messages between tags using git log v[OLD_VERSION]..v[NEW_VERSION] --oneline to auto-generate release note sections
5. Push annotated tags to remote with git push origin v[VERSION] or git push origin --tags for all tags
6. Verify tag details with git show v[VERSION] to confirm message, tagger, date, and commit SHA
7. Update a CHANGELOG.md file with new version entry before tagging: prepend section with version header, date, and categorized commit summaries
8. Delete incorrect tags locally with git tag -d v[VERSION] and from remote with git push origin --delete v[VERSION] before re-creating

Code

#!/bin/bash
set -euo pipefail

VERSION="${1:-}"
CHANGELOG_FILE="CHANGELOG.md"

# Validate semantic version format
validate_version() {
  local version="$1"
  if [[ ! "$version" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9]+)?(\+[a-zA-Z0-9]+)?$ ]]; then
    echo "Error: Invalid semantic version format: $version"
    echo "Expected format: v1.2.3 or 1.2.3 with optional pre-release and metadata"
    exit 1
  fi
}

# Normalize version to vX.Y.Z format
normalize_version() {
  local version="$1"
  [[ "$version" =~ ^v ]] && echo "$version" || echo "v$version"
}

# Extract previous tag for changelog generation
get_

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change