Automate Releases with semantic-release

By Khimananda Oli | Last reviewed: August 2026

Manually bumping version numbers and drafting changelogs is a bottleneck that introduces human error into every deployment cycle. When you automate releases with semantic-release, you tie versioning directly to your commit messages, ensuring that every merge to main produces an accurate, immutable artifact without developer intervention. This approach integrates tightly with modern CI workflows, such as those outlined in my guide on CI/CD best practices for small teams, transforming git history into a reliable source of truth for production deployments.

How do you configure semantic-release for automated versioning?

Configuration begins with treating your release process as code, not a manual ceremony. In 2026, the standard approach uses a .releaserc.json or release.config.js file at the repository root. This declarative configuration ensures that anyone cloning the repo can reproduce the exact release behavior, aligning with infrastructure-as-code principles discussed in Infrastructure as Code with Terraform.

Install dependencies and define plugins

You need the core package plus plugins for your specific ecosystem. For a typical Node.js or containerized application, install these as dev dependencies:

npm install --save-dev semantic-release @semantic-release/commit-analyzer @semantic-release/release-notes-generator @semantic-release/changelog @semantic-release/npm @semantic-release/git @semantic-release/github

Create a .releaserc.json file to orchestrate the plugin sequence. Order matters significantly here; the commit analyzer must run before notes generation, and assets must be prepared before publishing.

{
  "branches": ["main", {"name": "beta", "prerelease": true}],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/changelog", {
      "changelogFile": "CHANGELOG.md"
    }],
    "@semantic-release/npm",
    ["@semantic-release/git", {
      "assets": ["package.json", "CHANGELOG.md"],
      "message": "chore(release): ${nextRelease.version} [skip ci]"
    }],
    "@semantic-release/github"
  ]
}

This configuration tells the tool to analyze commits against the main branch, generate release notes, update the changelog file, bump the package.json version, commit those files back to the repo (skipping CI to prevent loops), and create a GitHub Release. For non-NPM projects like Go or Python binaries, replace @semantic-release/npm with @semantic-release/exec to run custom build scripts.

What are Conventional Commits and why are they required?

semantic-release cannot function without structured commit messages. It relies entirely on the Conventional Commits specification to map changes to semantic versions. A common mistake I see in audits is teams adopting the tool but failing to enforce message standards, resulting in skipped releases or incorrect version bumps.

• feat: Triggers a MINOR version bump (1.0.0 → 1.1.0). Use for new user-facing functionality.
• fix: Triggers a PATCH version bump (1.0.0 → 1.0.1). Use strictly for bug fixes.
• BREAKING CHANGE: Footer or ! after type triggers MAJOR bump (1.0.0 → 2.0.0). Required for API removals or schema changes.
• chore/docs/style: No version bump. These trigger a release only if configured, but typically just update metadata.

Enforce this locally using commitlint and husky. Add a pre-commit hook that rejects non-compliant messages before they ever reach the remote repository. This shifts quality left and prevents broken release pipelines. If a developer writes "fixed login bug" instead of "fix(auth): resolve token expiry on login", the automation ignores it. Discipline here is non-negotiable for reliable automation.

How do you integrate semantic-release into CI/CD pipelines?

The release step must run in a trusted CI environment with write access to your repository and package registry. Never run releases from local machines; this breaks the audit trail and violates SOC 2 change management controls. Below is a production-grade GitHub Actions workflow snippet:

name: Release
on:
  push:
    branches: [main]

permissions:
  contents: write
  issues: write
  pull-requests: write
  packages: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: false
      
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      
      - run: npm ci
      - run: npm run build
      
      - name: Semantic Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

Critical details often missed: fetch-depth: 0 is mandatory because the tool needs full git history to find the last tag. persist-credentials: false prevents the default token from being used for pushes; semantic-release uses its own authenticated context. For GitLab CI users following GitLab CI pipelines, use the CI_JOB_TOKEN and ensure the runner has maintainer permissions.

How does semantic-release compare to manual tagging and other tools?

Teams often ask whether they should stick to manual git tags or use alternatives like Changesets. The choice depends on team size, compliance requirements, and release cadence. In regulated environments where I've implemented ISO 27001 controls, deterministic automation always wins over human judgment.

Choose Changesets if your team prefers PR-centric workflows and maintains complex monorepos with interdependent packages. Choose semantic-release if you want zero-touch releases tied directly to trunk-based development. Manual tagging has no place in modern DevOps except for emergency hotfixes outside the pipeline.

What security and compliance considerations apply to automated releases?

Automating releases expands your attack surface. The CI token used by semantic-release has write access to your repository and potentially your package registry. Follow least-privilege principles as detailed in AWS IAM best practices:

1. Use fine-grained tokens: Never use a personal access token. Create a dedicated bot account or use OIDC federation with scoped permissions limited to content:write and packages:write.
2. Sign releases: Configure GPG signing for tags and commits. This provides cryptographic proof that the release originated from your trusted CI environment, satisfying supply chain security requirements.
3. Audit the changelog: Treat CHANGELOG.md as a compliance artifact. Review it during sprint retrospectives to verify that documented changes match actual deployed code.
4. Protect the main branch: Require status checks and signed commits. Prevent direct pushes that could bypass the release analyzer.

In Nepal's growing tech sector, where startups are increasingly seeking international clients requiring SOC 2 or ISO 27001 certification, this level of rigor differentiates professional engineering teams from hobbyist projects. Automated evidence collection starts with trustworthy release metadata.

Next Steps for Reliable Release Automation

To successfully automate releases with semantic-release, start by enforcing Conventional Commits locally before touching CI. Audit your existing commit history; if it's messy, consider squashing or rebasing to establish a clean baseline tag. Implement the pipeline incrementally: first dry-run mode (--dry-run) to validate version calculation, then enable GitHub releases only, and finally add package publishing once trust is established. Remember that automation amplifies both good and bad habits — disciplined commit hygiene is the foundation. If your team needs help designing compliant release pipelines or migrating legacy projects to automated versioning, reach out to discuss your specific requirements.