github-actions.md

Using semantic-release with GitHub Actions

Environment variables

The Authentication environment variables can be configured with Secret Variables.

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

Node project configuration

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

Note: The publish pipeline must run on Node version >= 10.18.

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

The following is a minimal configuration for semantic-release with a build running on Node 12 when a new commit is pushed to a master branch. See Configuring a Workflow for additional configuration options.

name: Release
on:
  push:
    branches:
      - master
jobs:
  release:
    name: Release
    runs-on: ubuntu-18.04
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 12
      - name: Install dependencies
        run: npm ci
      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

Pushing package.json changes to a master branch

To keep package.json updated in the master branch, @semantic-release/git 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 Personal Access Tokens, 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 acceptible, some extra configuration is needed. The actions/checkout persist-credentials option needs to be false, otherwise the generated GITHUB_TOKEN will interfere with the custom one. Example:

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

Trigger semantic-release on demand

Using GUI:

You can use Manual Triggers for GitHub Actions.

Using HTTP:

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

name: Release
on:
  repository_dispatch:
    types: [semantic-release]
jobs:
# ...

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

$ 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:

• Actions Panel - A declaratively configured way for triggering GitHub Actions
• Action Button - A simple badge based mechanism for triggering GitHub Actions