$devvkit learn --librarie semantic-release:-automated-releases-guide

semantic-release: Automated Releases Guide

[oss-stack][release][automation][semver][ci]

Open Source

Install

# In your project root
npm install --save-dev semantic-release

# Dry run first: see what it would do
npx semantic-release --dry-run

semantic-release removes the human from release engineering. It reads your commit history (Conventional Commits), decides the next version with semver rules (fix → patch, feat → minor, breaking → major), writes the changelog, creates the git tag, and publishes to the registry and GitHub Releases. No more "which version should this be?" meetings.

It runs in CI: typically `npx semantic-release` in a GitHub Actions job with the GITHUB_TOKEN permission. The only configuration file is the branch, plugins, and repository URL. Teams report release time dropping from an hour to zero, and the commit history becomes the single source of truth.

Setup

Install and dry run· Install and preview behavior without publishing.

npm install --save-dev semantic-release

# Dry run prints the next version and steps:
npx semantic-release --dry-run

# Full run (requires GITHUB_TOKEN in CI):
npx semantic-release

package.json config· Enable via scripts or a '.releaserc' file.

# package.json:
"release": { "branches": ["main"] }

# Or .releaserc.json:
{
  "branches": ["main", { "name": "next", "prerelease": true }],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    "@semantic-release/github"
  ]
}

Plugins

Commit analyzer· Maps commit types to version bumps.

# Built-in defaults:
# fix            -> PATCH  (1.0.1)
# feat           -> MINOR  (1.1.0)
# BREAKING CHANGE-> MAJOR (2.0.0)
# docs/style/etc -> no release

# Custom rules:
npm install --save-dev @semantic-release/commit-analyzer
# .releaserc: add "releaseRules" to promote/perf or block chore

GitHub plugin· Create releases and comment on issues/PRs linked to the release.

npm install --save-dev @semantic-release/github

# Creates a GitHub Release from the changelog
# and adds a comment to issues closed by the release.
# Set permissions:
# contents: write  issues: write

npm publish· Publish to the registry from CI.

npm install --save-dev @semantic-release/npm

# package.json must include:
"publishConfig": { "access": "public" }
# CI needs NPM_TOKEN set in secrets.

Verify release· Gate releases with quality checks.

npm install --save-dev @semantic-release/exec

# .releaserc:
{
  "verifyConditions": ["@semantic-release/exec"],
  "verifyRelease": [
    { "path": "@semantic-release/exec",
      "verifyConditionsCmd": "npm test"
    }
  ]
}

# Or simpler: run tests as a separate CI step before release.

CI Integration

GitHub Actions workflow· The standard release pipeline.

name: Release
on:
  push:
    branches: [main]
permissions:
  contents: write
  issues: write
  pull-requests: write
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, registry-url: https://registry.npmjs.org/ }
      - run: npm ci
      - run: npm test
      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}