Adding semantic-release to GitHub Actions

Let semantic-release decide the next version from your commits and publish it automatically.

semantic-release reads Conventional Commits to compute the next version, then tags, creates a GitHub Release, and publishes to npm - no manual version bumps. It runs on pushes to your release branch and needs tokens for GitHub and the registry.

What you need

• Conventional Commit messages in history.
• A .releaserc with your plugins.
• GITHUB_TOKEN (contents/issues write) and NPM_TOKEN if publishing.

The workflow

Run semantic-release on the release branch with tokens.

permissions:
  contents: write
  issues: write
  pull-requests: write
steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0
  - uses: actions/setup-node@v4
    with:
      node-version: 20
  - run: npm ci
  - run: npx semantic-release
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Common gotchas

• It needs full history (fetch-depth: 0) to analyze commits and tags.
• Non-conventional commits produce no release - enforce the format in PRs.
• Publishing needs the npm 2FA setting to allow automation tokens.

Key takeaways

• semantic-release derives versions from Conventional Commits.
• Use fetch-depth: 0 so it can analyze full history.
• Provide GITHUB_TOKEN and NPM_TOKEN for releases and publishing.

Related guides