Auto Release Workflow

Auto Release Workflow

Automated versioning and release creation on every merge to main.

How It Works

1. Code is merged to main branch
2. GitHub Actions workflow triggers
3. Gets latest git tag (defaults to v0.0.0 if none)
4. Auto-increments patch version
5. Creates new git tag
6. Generates release notes from commits
7. Creates GitHub Release

Versioning Strategy

Uses Semantic Versioning: MAJOR.MINOR.PATCH

Automatic (Patch)

Every merge to main auto-increments patch:

• v1.0.0 → v1.0.1
• v1.0.1 → v1.0.2
• v1.0.2 → v1.0.3

Manual (Major/Minor)

Use the bump script for bigger changes:

# Bump minor version (1.0.5 → 1.1.0)
./scripts/bump-version.sh minor

# Bump major version (1.2.5 → 2.0.0)
./scripts/bump-version.sh major

When to Use Each

• Patch (automatic): Bug fixes, small changes
• Minor (manual): New features, backward-compatible
• Major (manual): Breaking changes

First Release

Option 1: Start with v0.0.1

Just merge code to main. Auto-release creates v0.0.1.

Option 2: Start with v1.0.0

Create initial tag manually:

git tag -a v1.0.0 -m "Initial release"
git push origin v1.0.0

Next merge will create v1.0.1.

Setup Requirements

Enable GitHub Actions Permissions

1. Go to: Settings → Actions → General
2. Scroll to "Workflow permissions"
3. Select "Read and write permissions"
4. Click Save

This allows the workflow to create tags and releases.

Release Notes

Release notes are auto-generated from commit messages between tags.

Example:

## What's Changed

- feat: add user authentication
- fix: resolve login bug
- docs: update README

Full Changelog: v1.0.0...v1.0.1

Tip: Use clear commit messages for better release notes.

Manual Version Bump Script

Usage

# Show current version and bump patch
./scripts/bump-version.sh

# Bump minor version
./scripts/bump-version.sh minor

# Bump major version
./scripts/bump-version.sh major

What It Does

1. Gets latest tag
2. Increments version based on type
3. Asks for confirmation
4. Creates and pushes new tag
5. Auto-release workflow creates the release

Troubleshooting

Workflow Not Running

• Check GitHub Actions is enabled
• Check "Read and write permissions" is set
• Look at Actions tab for errors

No Tags Found

First merge creates v0.0.1. If you want v1.0.0, create it manually first.

Multiple Tags Created

If you push directly to main multiple times rapidly, each push creates a tag. Use PRs to batch changes.

Example Workflow

# Work on feature branch
git checkout -b feature/new-feature
# ... make changes ...
git commit -m "feat: add new feature"
git push origin feature/new-feature

# Create PR and merge to main
# → Auto-release creates v1.0.1

# Need minor version bump?
git checkout main
git pull
./scripts/bump-version.sh minor
# → Creates v1.1.0

# Continue development...