Skip to main content

Getting Started

This action allows you to automate the release process of your npm modules, apps and actions. It can fetch OTP for npm on the fly using either Optic or through a alternative way of providing OTP.

What does it do?​

  • When run, it opens a new PR for the release.
  • When/if the PR gets merged, it publishes a new npm release, a new GitHub release with changelogs and it adds a comment for each issues linked to the release with links to the release details. This feature can be turned off by the notify-linked-issues flag.

You can also use it for releases without npm. In that case, when the PR merges, a new GitHub release will be published. Which you can use to trigger another workflow that deploys the app somewhere (GCP, AWS etc).

Usage​

  • Install the optic-release-automation GitHub app to your organization (or selected repositories)
  • Create a new workflow file at .github/workflows/release.yml (from example below) with one step that uses this action and supply the inputs.

Note that the on triggers are mandatory:

  • workflow_dispatch: to start the new release process
  • pull_request when closed: to complete the release process when the PR is merged

Example​

This example shows how to configure this action to release a new npm package version:

name: release

on:
  workflow_dispatch:
    inputs:
      semver:
        description: 'The semver to use'
        required: true
        default: 'patch'
        type: choice
        options:
          - auto
          - patch
          - minor
          - major
          - prerelease
          - prepatch
          - preminor
          - premajor
      baseTag:
        description: 'base release tag'
      tag:
        description: 'The npm tag'
        required: false
        default: 'latest'
      commit-message:
        description: 'The commit message template'
        required: false
        default: 'Release {version}'
  pull_request:
    types: [closed]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
      # optional: `id-token: write` permission is required if `provenance: true` is set below
      id-token: write
    steps:
      - uses: nearform-actions/optic-release-automation-action@v4
        with:
          commit-message: ${{ github.event.inputs.commit-message }}
          semver: ${{ github.event.inputs.semver }}
          npm-tag: ${{ github.event.inputs.tag }}
          # optional: set this secret in your repo config for publishing to npm
          npm-token: ${{ secrets.NPM_TOKEN }}
          # optional: set this secret in your repo config for 2FA with Optic
          optic-token: ${{ secrets.OPTIC_TOKEN }}
          # optional: set this secret in your repo config for using alternative way of providing OTP
          ngrok-token: ${{ secrets.NGROK_TOKEN }}
          # optional: npm will generate provenance statement, or abort release if it can't
          provenance: true

NPM OTP Authentication​

The action supports two methods for handling npm 2FA:

  1. Optic Flow: Uses the Optic mobile app for OTP generation. Requires optic-token.
  2. Alternative way of providing OTP: Provides a web interface for manual OTP entry. Requires ngrok-token.

You can configure either or both methods:

  • Set optic-token to use Optic mobile flow
  • Set ngrok-token to enable web UI flow. When enabled, the action provides a secure URL where you can manually enter the npm OTP.

The above workflow (when manually triggered) will:

  • Checkout the repository source code
  • Run npm version <semver> command to bump the version as configured (patch, minor, etc)
  • Execute the build-command if configured
  • Commit the changes and push to the release/${new semver version} branch
  • Open a PR that looks like following

image

When you merge this PR:

  • It will request an npm OTP from Optic.
  • (Optional) You can define npm and Optic tokens in GitHub secrets for each user that will receive the OTP. This is required only in case you want to publish to npm.
  • Upon successful retrieval of the OTP, it will publish the package to npm.
  • Create a Github release with change logs (You can customize release notes using release.yml)
  • Leave a comment on each issues that are linked to the pull requests of this release. This feature can be turned off by the notify-on-the-issue flag.
  • (Optional) If provenance: true, npm will add a Provenance notice to the package's public npm page.

When you close the PR without merging it: nothing will happen.

Using the 'auto' bump version option​

If you choose the "auto" option for semver version updates, the action will attempt to determine the new version number based on the commit messages. For this option to work, the repository must use the conventional commits standard. You can refer the conventional commits documentation for more information.

Creating prereleases​

This action can be used to create prereleases.

In order to do that you can configure your action adding the npm version parameters prerelease|prepatch|preminor|premajor in the semver options.

It's possible to specify a custom prerelease-prefix if you want to have one. This will be added as a prefix to the prerelease version. Let's suppose we want to use next as a prerelease-prefix, the prerelease version will be something like: v1.0.0-next.1.

The prerelease-prefix is used as the input for the --preid in the npm version command.

An important note is that the prerelease-prefix is used to identify the release version, on the other hand we have the npm-tag which is responsible of identifying the proper npm tag when a package is published to npm, e.g.: latest|experimental|next|rc|beta.

Generally, if you want to release a prerelease of a repository, and it is an npm package, you usually want to use prerelease-prefix and npm-tag inputs together.

Please note that in case of a prerelease the sync-semver-tags input will be treated as false, even if it's set to true. This because we don't want to update the main version tags to the latest prerelease commit but only to the latest official release.

Provenance​

If provenance: true is added to your release.yml's inputs, npm will generate a provenance statement.

npm has some internal requirements for generating provenance. Unfortunately as of May 2023, not all are documented by npm; some key requirements are:

  • id-token: write must be added to your release.yml's permissions
  • The package must have public access.
  • npm must be on version 9.5.0 or greater (this will be met if our recommended runs-on: ubuntu-latest is used)
  • npm has some undocumented internal requirements on package.json completeness. For example, the repository field is required, and some npm versions may require its "url" property to match the format "git+https://github.com/user/repo".

If any requirements are not met, the release will be aborted before publishing the new version, and an appropriate error will be shown in the actions report. The release commit can be reverted and the action re-tried after fixing the issue highlighted in the logged error.

The above example yml action includes support for Provenance. To add provenance support to an existing action, add these two lines:

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
      # add this permission which is required for provenance
      id-token: write
    steps:
      - uses: nearform-actions/optic-release-automation-action@v4
        with:
          npm-token: ${{ secrets.NPM_TOKEN }}
          optic-token: ${{ secrets.OPTIC_TOKEN }}
          commit-message: ${{ github.event.inputs.commit-message }}
          semver: ${{ github.event.inputs.semver }}
          npm-tag: ${{ github.event.inputs.tag }}
          # add this to activate the action's provenance feature
          provenance: true