semantic-release
AboutGitHubNeed Help?
master
master
  • README
  • Usage
    • Getting started
    • Installation
    • CI Configuration
    • Configuration
    • Plugins
    • Release Workflow configuration
    • Shareable configurations
  • Extending
    • Plugins
    • Shareable configuration
  • Recipes
    • CI configurations
      • CircleCI 2.0
      • Travis CI
      • GitLab CI
      • GitHub Actions
      • Jenkins CI
    • Git hosted services
      • Git authentication with SSH keys
    • Release Workflow
      • Publishing on distribution channels
      • Publishing maintenance releases
      • Publishing pre-releases
  • Developer guide
    • JavaScript API
    • Plugin development
    • Shareable configuration development
  • Support
    • Resources
    • Frequently Asked Questions
    • Troubleshooting
    • Node version requirement
    • Node Support Policy
    • Git version requirement
Powered by GitBook
On this page
  • Environment variables
  • npm provenance
  • Node project configuration
  • .github/workflows/release.yml configuration for Node projects
  • Pushing package.json changes to your repository
  • Trigger semantic-release on demand
  • Using GUI:
  • Using HTTP:
  • Using 3rd party apps:
Edit on GitHub
  1. Recipes
  2. CI configurations

GitHub Actions

PreviousGitLab CINextJenkins CI

Last updated 3 months ago

Environment variables

The environment variables can be configured with .

In this example a publish type is required to publish a package to the npm registry. GitHub Actions a environment variable which can be used in Workflows.

npm provenance

Since GitHub Actions is a for , it is recommended to enable this to increase supply-chain security for your npm packages. Find more detail about configuring npm to publish with provenance through semantic-release .

Node project configuration

support , allowing to run tests on multiple Node versions and publish a release only when all test pass.

Note: The publish pipeline must run on a .

.github/workflows/release.yml configuration for Node projects

The following is a minimal configuration for with a build running on the latest LTS version of Node when a new commit is pushed to a master/main branch. See the for additional configuration options.

name: Release
on:
  push:
    branches:
      - master # or main

permissions:
  contents: read # for checkout

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    permissions:
      contents: write # to be able to publish a GitHub release
      issues: write # to be able to comment on released issues
      pull-requests: write # to be able to comment on released pull requests
      id-token: write # to enable use of OIDC for npm provenance
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "lts/*"
      - name: Install dependencies
        run: npm clean-install
      - name: Verify the integrity of provenance attestations and registry signatures for installed dependencies
        run: npm audit signatures
      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

Pushing package.json changes to your repository

- name: Checkout
  uses: actions/checkout@v2
  with:
    fetch-depth: 0
    persist-credentials: false # <--- this

Trigger semantic-release on demand

Using GUI:

Using HTTP:

name: Release
on:
  repository_dispatch:
    types: [semantic-release]
jobs:
# ...
$ curl -v -H "Accept: application/vnd.github.everest-preview+json" -H "Authorization: token ${GITHUB_TOKEN}" https://api.github.com/repos/[org-name-or-username]/[repository]/dispatches -d '{ "event_type": "semantic-release" }'

Using 3rd party apps:

If you'd like to use a GitHub app to manage this instead of creating a personal access token, you could consider using a project like:

If you choose to commit changes to your package.json , the plugin can be used.

Note: Automatically populated GITHUB_TOKEN cannot be used if branch protection is enabled for the target branch. It is not advised to mitigate this limitation by overriding an automatically populated GITHUB_TOKEN variable with a , as it poses a security risk. Since Secret Variables are available for Workflows triggered by any branch, it becomes a potential vector of attack, where a Workflow triggered from a non-protected branch can expose and use a token with elevated permissions, yielding branch protection insignificant. One can use Personal Access Tokens in trusted environments, where all developers should have the ability to perform administrative actions in the given repository and branch protection is enabled solely for convenience purposes, to remind about required reviews or CI checks.

If the risk is acceptable, some extra configuration is needed. The option needs to be false, otherwise the generated GITHUB_TOKEN will interfere with the custom one. Example:

You can use for GitHub Actions.

Use event to have control on when to generate a release by making an HTTP request, e.g.:

To trigger a release, call (with a stored in GITHUB_TOKEN environment variable):

- A declaratively configured way for triggering GitHub Actions

- A simple badge based mechanism for triggering GitHub Actions

Personal Access Tokens
actions/checkout persist-credentials
Manual Triggers
repository_dispatch
Personal Access Tokens
Actions Panel
Action Button
Secret Variables
NPM_TOKEN
automatically populate
GITHUB_TOKEN
supported provider
npm provenance
in the documentation for our npm plugin
GitHub Actions
Workflows
Node version that meets our version requirement
semantic-release
Workflow syntax for GitHub Actions
@semantic-release/git
Authentication
against our recommendation