optic-release-automation-action

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 Optic.

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 and a new GitHub release with change logs

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"
      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
    steps:
      - uses: nearform/optic-release-automation-action@v2
        with:
          github-token: ${{ secrets.github_token }}
          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 }}

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

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)

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

Multiple user scenario

In case there are multiple users who have access to trigger the release automation action, you can define Npm and Optic tokens for different users in GitHub secrets. Following is an example of a way to use different tokens depending on the user who merged the pull request.

Example:

Use only default tokens: e.g. npm-token: ${{ secrets.NPM_TOKEN }}
Use only user-related tokens: e.g. npm-token: ${{ secrets[format('NPM_TOKEN_{0}', github.actor)] }}
Use both user-related and default token: e.g. npm-token: ${{ secrets[format('NPM_TOKEN_{0}', github.actor)] || secrets.NPM_TOKEN }}

# ...
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: nearform/optic-release-automation-action@v2
        with:
          github-token: ${{ secrets.github_token }}
          npm-token: ${{ secrets[format('NPM_TOKEN_{0}', github.actor)] || secrets.NPM_TOKEN }}
          optic-token: ${{ secrets[format('OPTIC_TOKEN_{0}', github.actor)] || secrets.OPTIC_TOKEN }}
          semver: ${{ github.event.inputs.semver }}
          npm-tag: ${{ github.event.inputs.tag }}

Note: Not all symbols that can be used in GitHub usernames are valid in secret names. One such example is the hyphen symbol (-). In such cases, this approach will not work.

How to add a build step to your workflow

When your project needs a build step, you can provide it to this action! The build-command option accepts a string that will be executed as a shell command (you can use yarn or your preferred build tool).

It is important to be aware that you are responsible for:

The context where the command is executed.
The command will be executed using the current GitHub runner configuration (e.g. the one set on runs-on). You can customize it by executing additional steps before the nearform/optic-release-automation-action step execution as shown in the next example.
The command to build the project, starting from the installation to the cleanup if needed.
You can set any automations like git hooks or pre/post scripts to execute within the build-command step.

The build's output will be committed to the release/${new semver version} branch, unless the project's .gitignore blocks it.
In that case, the build's output will be packed into the Npm package during the release process.

Here an example using npm to build the project:

# ...
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Optionally configure your preferred runtime
        uses: actions/setup-node@v2
        with:
          node-version: 14 # setting a specific version of node as an example

      - uses: nearform/optic-release-automation-action@v2
        with:
          github-token: ${{ secrets.github_token }}
          npm-token: ${{ secrets.NPM_TOKEN }}
          optic-token: ${{ secrets.OPTIC_TOKEN }}
          semver: ${{ github.event.inputs.semver }}
          build-command: |
            npm install
            npm run build

Inputs

Input	Required	Description
`github-token`	Yes	This is your GitHub token, it's already available to your GitHub action
`semver`	Yes	The version you want to bump (`patch
`commit-message`	No	The commit message template. The keyword `{version}` will be replaced with the new version. (Default: `Release {version}`)
`npm-token`	No	This is your Npm Publish token. Read how to create acccess tokens. Required only if you want to release to Npm. If you omit this, no Npm release will be published.
`optic-url`	No	URL if you have a custom application that serves OTP. (Default: )
`optic-token`	No	This is your Optic token. You can add your Npm secret to the Optic app, generate a token and pass it to this input. (If skipped, no OTP is requested while publishing. Useful when you want to use Automation token instead of Publish token. Read more
`actor-name`	No	The name you want to see in the new release commit. (Default: User who triggered the release workflow)
`actor-email`	No	The email you want to see in the new release commit. (Default: User who triggered the release workflow)
`npm-tag`	No	If you want to release to the Npm with a custom tag, say `next`. (Default: `latest`)
`build-command`	No	An optional build commit to run after the version bump and before releasing the package
`api-url`	No	GitHub App URL. You wouldn't need to set this unless you're deploying a custom GitHub app instead of optic-release-automation. (Default: `https://optic-release-automation-ocrlhra4va-ue.a.run.app/`)
`sync-semver-tags`	No	If you want to keep the major and minor versions tag synced to the latest appropriate commit (Default: `false`)

Motivation

Why do I need this when I can create Npm automation tokens?

An automation token will bypass two-factor authentication when publishing. If you have two-factor authentication enabled, you will not be prompted when using an automation token, making it suitable for CI/CD workflows.

Although you can generate a Npm token that would let you bypass the OTP while publishing, this service lets you use the Publish token and generate a token on the fly while publishing. It will request Optic service which would request OTP from your phone and only after your approval, will the release proceed.

ja-bravo/optic-release-automation-action