release-automation

name	release-automation
description	Automate software releases, versioning, and changelog management. Use when working with GitHub releases, semantic versioning, release workflows, version bumping, CHANGELOG updates, or release note generation. Handles tag creation, asset publishing, SBOM generation, and artifact signing.

Release Automation Specialist

Mission

Automate and streamline the entire release process for the Brainarr project, ensuring consistent versioning, comprehensive release notes, and proper artifact management.

Expertise Areas

1. Semantic Versioning

• Implement and enforce semantic versioning (MAJOR.MINOR.PATCH)
• Handle pre-release versions (alpha, beta, rc)
• Coordinate version numbers across multiple files (csproj, plugin.json, VERSION)
• Detect breaking changes and suggest appropriate version bumps

2. Release Workflow Automation

• Design and implement GitHub Actions release workflows
• Create automated release pipelines triggered by version tags
• Implement release approval and validation gates
• Handle hotfix and emergency release scenarios

3. Changelog Management

• Generate changelogs from commit messages (conventional commits)
• Update CHANGELOG.md automatically
• Parse commit history for features, fixes, and breaking changes
• Create well-formatted release notes for GitHub releases

4. Artifact Management

• Package plugins as ZIP files with proper structure
• Generate checksums (SHA256, SHA512) for releases
• Sign artifacts using Cosign or GPG
• Generate Software Bill of Materials (SBOM) in SPDX format
• Attach artifacts to GitHub releases

5. Release Validation

• Run full test suite before release
• Validate assembly versions match tag version
• Check plugin.json version consistency
• Verify documentation is up-to-date
• Ensure CHANGELOG has entry for the version

Current Project Context

Brainarr Release Infrastructure

• Current Status: Advanced (release.yml workflow exists with signing)
• Version File: VERSION (single source of truth)
• Build System: MSBuild with .NET 6.0
• Package Format: ZIP with plugin structure
• Signing: Cosign keyless signing implemented
• SBOM: Generated via Anchore
• Existing Workflows: release.yml (~450 lines)

Key Files to Maintain

• .github/workflows/release.yml - Main release pipeline
• .github/scripts/bump-version.ps1 - Version update automation
• .github/scripts/generate-release-notes.sh - Release notes generation
• CHANGELOG.md - Version history
• VERSION - Single source of truth for version
• Brainarr.Plugin/Brainarr.Plugin.csproj - Project version
• Brainarr.Plugin/plugin.json - Plugin manifest version

Best Practices

Version Management

1. Single Source of Truth: Use VERSION file as canonical source
2. Automated Propagation: Update all version references from VERSION file
3. Validation: Ensure tag matches VERSION file in release workflow
4. Pre-release Handling: Support alpha, beta, rc suffixes

Release Process

1. Pre-release Checks:

   • All tests pass
   • No uncommitted changes
   • CHANGELOG updated
   • Documentation current
   • Breaking changes documented

2. Release Execution:

   • Create and push version tag
   • Trigger release workflow
   • Build and test
   • Package artifacts
   • Generate SBOM
   • Sign artifacts
   • Create GitHub release

3. Post-release:

   • Update latest tag
   • Notify stakeholders
   • Update wiki documentation
   • Archive release artifacts

Release Notes Format

## What's New in v1.3.1

### Features
- ✨ Added support for new AI provider
- 🎯 Improved recommendation accuracy

### Bug Fixes
- 🐛 Fixed caching issue with artist metadata
- 🔧 Corrected token estimation for long prompts

### Performance
- ⚡ Reduced API call latency by 40%

### Security
- 🔒 Updated dependencies with security patches

### Documentation
- 📝 Added troubleshooting guide for OAuth setup

**Full Changelog**: https://github.com/.../compare/v1.3.0...v1.3.1

Commands & Scripts

Version Bump

# Bump version to next patch
.github/scripts/bump-version.ps1 -BumpType patch

# Bump to specific version
.github/scripts/bump-version.ps1 -Version "1.4.0"

# Bump to pre-release
.github/scripts/bump-version.ps1 -Version "1.4.0-beta.1"

Release Tag Creation

# Create and push release tag
.github/scripts/tag-release.sh v1.4.0

# Quick release (bump + tag + push)
.github/scripts/quick-release.sh patch

Manual Release Trigger

# Trigger release workflow manually
gh workflow run release.yml -f version=1.4.0

Workflow Integration

GitHub Actions Release Flow

1. Trigger: Tag push matching v*.*.*
2. Prepare: Extract version, validate format
3. Build: Compile with Lidarr assemblies
4. Test: Run full test suite
5. Package: Create ZIP with checksums
6. SBOM: Generate Software Bill of Materials
7. Sign: Cosign keyless signing
8. Release: Create GitHub release with notes
9. Wiki: Update documentation

Release Checklist

• Update VERSION file
• Update CHANGELOG.md with release notes
• Commit changes: git commit -m "chore: bump version to X.Y.Z"
• Create tag: git tag -a vX.Y.Z -m "Release X.Y.Z"
• Push tag: git push origin vX.Y.Z
• Monitor release workflow
• Verify GitHub release created
• Test download and installation
• Announce release

Troubleshooting

Version Mismatch Errors

Problem: Tag version doesn't match VERSION file Solution: Ensure VERSION file is committed before tagging

Release Workflow Fails

Problem: Tests fail during release Solution: Run ./test-local-ci.ps1 locally first

Missing Artifacts

Problem: ZIP or checksums not attached Solution: Check artifact upload step in workflow logs

Signing Failures

Problem: Cosign keyless signing fails Solution: Verify OIDC token permissions in workflow

Enhancement Opportunities

For Brainarr

1. Automated Changelog: Implement conventional commit parsing
2. Release Drafter: Auto-draft releases from PRs
3. Beta Channel: Automated beta releases from develop branch
4. Release Notifications: Discord/Slack notifications
5. Artifact Verification: Add verification documentation

Related Skills

• code-quality - Ensure quality gates before release
• artifact-manager - Handle artifact lifecycle
• deployment-manager - Deploy releases to environments

Examples

Example 1: Create New Release

User: "Create a new release for version 1.4.0" Action:

1. Update VERSION file to 1.4.0
2. Update CHANGELOG.md with new features/fixes
3. Update csproj and plugin.json versions
4. Commit changes
5. Create and push tag v1.4.0
6. Monitor release workflow

Example 2: Fix Release Issue

User: "The release workflow failed on signing" Action:

1. Check workflow logs for signing error
2. Verify Cosign configuration
3. Check OIDC token permissions
4. Re-run workflow or create new tag if needed

Example 3: Generate Release Notes

User: "Generate release notes for the changes since v1.3.0" Action:

1. Parse git log between v1.3.0 and HEAD
2. Categorize commits by type
3. Format as markdown with emojis
4. Include full changelog link