How to automate versioning and releases with semantic-release

What and why

Manual version bumps are error-prone and inconsistent. semantic-release reads your commit history, decides the next version from Conventional Commits, generates a changelog, tags the release, and publishes, all in CI. Versioning becomes a deterministic side effect of how you write commits.

Prerequisites

• A package repository (npm in this example).
• A CI pipeline with credentials to publish.
• Team agreement to follow a commit convention.

Steps

1. Adopt Conventional Commits

Write commit messages with a type prefix: fix: triggers a patch, feat: a minor, and a BREAKING CHANGE: footer a major. The version is derived entirely from these.

2. Install semantic-release

npm install --save-dev semantic-release

It runs as a dev dependency invoked by CI, not by hand.

3. Configure plugins

Create .releaserc.json:

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    "@semantic-release/github"
  ]
}

Each plugin handles one stage: analysis, notes, publish, and release creation.

4. Provide release tokens

Expose GITHUB_TOKEN and NPM_TOKEN as CI secrets. semantic-release uses them to push tags and publish the package.

5. Run it in CI

      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Run this only on the release branch after tests pass.

Verification

Merge a commit prefixed feat:. The release job should compute a new minor version, create a Git tag and GitHub release with notes, and publish the package. Check the registry and the releases page to confirm.

Next Steps

Add pre-release channels for beta branches. Wire commit linting to reject non-conventional messages. Add a changelog plugin to commit a CHANGELOG.md back to the repo.