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