Semantic Version Automation Release Workflow

Derive versions from conventional commit messages, generate changelogs automatically, and publish artifacts only from tagged green builds.

intermediate~35 minreleaseautomationversioning

Objective

Release versions derived from commit intent with zero manual version editing and a trustworthy generated changelog.

Environment

Conventional Commits enforced by a hook or CI check
A release automation tool such as semantic-release
Publish credentials for the package registry or artifact store

Steps

1. Enforce commit message format

Install commitlint with the conventional config and a commit-msg hook plus a CI check, so feat, fix, and BREAKING CHANGE reach the tool intact.

Expected state: Non-conforming commits are rejected locally and in CI.

2. Configure the release tool

Set up semantic-release with the plugins for commit analysis, changelog generation, npm or artifact publishing, and git tags.

Expected state: A dry-run prints the would-be version and changelog sections without publishing.

3. Run dry-run against recent history

Execute the release in dry-run mode and compare the computed version bump and notes against what humans would have written.

Expected state: The generated notes correctly group features, fixes, and breaking changes with links to commits.

4. Automate on the main pipeline

Add the release step to CI on main after tests pass, gated on the branch being exactly main and the build being green.

Expected state: Merges to main now produce a release (or a deliberate no-release) without human version edits.

5. Verify the published chain

Confirm the published artifact version, the git tag, and the changelog entry all reference the same commit hash.

Expected state: Version, tag, and changelog align on one hash with no manual corrections.

Decision points

Publish every green main build or batch weekly?

Every merge
Scheduled batch

Every merge for libraries (consumers want fixes fast); batch for applications where release overhead still matters.

What about commits that skip the format?

Block entirely
Allow with default type fix

Block in CI after a grace period; silent defaults corrupt versioning trust faster than a rejected commit annoys anyone.

Expected outcome

Versions and changelogs that are a pure function of commit history, published only from green main builds, with no manual version bumps anywhere.

Verification

Inspect the last three releases: each tag resolves to a green CI run, the changelog matches the commit log grouping, and no version file was hand-edited in the diff.

The commit log is the release input

Manual version bumps drift from reality: someone marks a patch for a feature, forgets a breaking change, or edits the changelog to sound better. Deriving both from conventional commits makes the release a function of recorded intent that anyone can audit.

history                    -> computed release
-------------------------------------------
feat: add coupon engine     
fix: correct rounding        -> 1.9.0  (minor)

feat!: drop legacy API      -> 2.0.0  (major, BREAKING)

chore: update deps          -> (no release)

changelog: generated, grouped
  feat / fix / BREAKING, with commit links

Dry-run is the adoption bridge

Running the tool in dry-run against months of existing history shows exactly how versions and notes would have looked, exposing bad commit habits before they become bad releases. Teams that skip this step discover format violations as surprise majors in production.

Guard the main-only gate

The release step must be branch-exact: running on feature branches or release attempts elsewhere either double-publishes or burns version numbers. The CI condition should test the ref name, not trust the caller.