Workflows

Reusable workflows for use in the Fastify organization.

Intro

GitHub introduced reusable workflows on 2021-11-29 which, as the name suggests, are workflows that can be referenced across the entirety of GitHub. A reusable workflow is called by using the uses keyword in another workflow.

For more information, including limitations, see the GitHub Docs.

CI workflows

Usage

name: CI

on:
  push:
    branches:
     - main
     - next
     - 'v*'
    paths-ignore:
      - 'docs/**'
      - '*.md'
  pull_request:
    paths-ignore:
      - 'docs/**'
      - '*.md'

permissions:
  contents: read

jobs:
  test:
    permissions:
      contents: write
      pull-requests: write
    uses: fastify/workflows/.github/workflows/plugins-ci.yml@v5

Included in this repo is a basic workflow for use across the majority of plugins, as well as variants with service containers.

Enable workflow Linter job

By setting the lint option to true when using the basic workflow the CI will first run the linter job once.

Example: running the linter job first with the basic workflow

name: CI

on:
  push:
    branches:
     - main
     - next
     - 'v*'
    paths-ignore:
      - 'docs/**'
      - '*.md'
  pull_request:
    paths-ignore:
      - 'docs/**'
      - '*.md'

permissions:
  contents: read

jobs:
  test:
    permissions:
      contents: write
      pull-requests: write
    uses: fastify/workflows/.github/workflows/plugins-ci.yml@v5
    with:
      lint: true

Inputs

Input Name	Required	Type	Default	Description
auto-merge-exclude	false	string	fastify	Provide a semicolon separated list of packages that you do not want to be auto-merged.
fastify-dependency-integration	false	boolean	false	Set to true to run fastify tests with the (proposed) changes.
license-check	false	boolean	false	Set to true to check that a repository's production dependencies use permissive licenses: 0BSD, Apache-2.0, BSD-2-Clause, BSD-3-Clause, MIT, or ISC.
license-check-allowed-additional	false	string		Provide a semicolon separated list of SPDX-license identifiers that you want to additionally allow.
lint	false	boolean	false	Set to true to run the lint script in a repository's package.json.
node-versions	false	string	'["24", "26"]'	Provide A JSON array that specifies the Node.js versions on which the job should run.

Release workflow

reusable-release.yml is a reusable workflow that bumps the package version, publishes it to npm with provenance and creates the matching GitHub release.

It authenticates to npm through OIDC, so the consuming package must be configured as a trusted publisher on npm. No NPM_TOKEN secret is needed.

If the repository defines a release:build script in its package.json, it is executed after the dependencies are installed and before npm publish. Note that this workflow does not run the test suite: the CI workflow is expected to have already validated the commit being released.

Usage

Add a .github/workflows/reusable-release.yml file to your repository:

name: release

on:
  workflow_dispatch:
    inputs:
      semver:
        description: 'Release bump type'
        required: true
        type: choice
        options:
          - patch
          - minor
          - major

permissions: {}

jobs:
  release:
    permissions:
      id-token: write
      contents: write
    uses: fastify/workflows/.github/workflows/reusable-release.yml@v7
    with:
      semver: ${{ inputs.semver }}

Then run it from the Actions tab, choosing the bump type.

See Restricting who can release to limit the maintainers that are allowed to approve a release.

Inputs

Input Name	Required	Type	Default	Description
semver	true	string		The release bump type: patch, minor, major, prepatch, preminor, premajor or prerelease.
preid	false	string	''	The prerelease identifier (e.g. rc) used by the pre* bump types.
node-version	false	string	lts/*	The Node.js version used to build and publish the package.
runs-on	false	string	ubuntu-latest	The runner used to publish the package.
environment	false	string	release	The deployment environment that gates the release.
dist-tag	false	string	latest	The npm dist-tag to publish under.
make-latest	false	boolean	true	Whether to mark the GitHub release as the latest one.

Releasing from a maintenance branch

When releasing an older major from a maintenance branch (e.g. v2.x), publish under a dedicated dist-tag and do not mark the GitHub release as the latest, so the current major keeps the latest tag:

    uses: fastify/workflows/.github/workflows/reusable-release.yml@v7
    with:
      semver: ${{ inputs.semver }}
      dist-tag: two
      make-latest: false

Run the workflow from the Actions tab selecting the maintenance branch.

Prereleases

The prepatch, preminor, premajor and prerelease bump types publish a prerelease (e.g. 5.0.0-rc.0 with preid: rc). The GitHub release is flagged as a prerelease and never marked as the latest one. Publishing a prerelease under the latest dist-tag is refused, so set dist-tag (e.g. next) as well:

on:
  workflow_dispatch:
    inputs:
      semver:
        description: 'Release bump type'
        required: true
        type: choice
        options:
          - patch
          - minor
          - major
          - prepatch
          - preminor
          - premajor
          - prerelease
      preid:
        description: 'Prerelease identifier (e.g. rc), used by the pre* bump types'
        required: false
        type: string

jobs:
  release:
    permissions:
      id-token: write
      contents: write
    uses: fastify/workflows/.github/workflows/reusable-release.yml@v7
    with:
      semver: ${{ inputs.semver }}
      preid: ${{ inputs.preid }}
      dist-tag: ${{ startsWith(inputs.semver, 'pre') && 'next' || 'latest' }}

Required permissions

The calling job must grant id-token: write (npm provenance via OIDC) and contents: write (to push the release commit and the tag).

Restricting who can release

GitHub Actions has no per-workflow access control: anyone with write access to a repository can start a workflow_dispatch run. To restrict releases to a specific set of maintainers, the job runs inside a deployment environment (release by default, configurable through the environment input).

In the consuming repository, go to Settings -> Environments, create the release environment and:

• add the team that is allowed to release (for example fastify/release) as a required reviewer, so every run pauses until one of them approves it;
• enable Prevent self-review, so the person who started the run cannot approve their own release;
• optionally limit the deployment branches to main.

Until the environment is approved no step of the job runs, so an unauthorised dispatch cannot bump the version nor publish anything.

Important

An environment that is referenced but never configured is created automatically without any protection rule. Creating the environment and adding the reviewers is a manual, per-repository step.

The same environment name can also be set as the Environment field of the npm trusted publisher configuration, so that npm itself rejects any publish that does not come from it.

Acknowledgments

Past sponsors:

• Yeovil Hospital

Contributing

Contributions are welcome, and any help is greatly appreciated!

See the contributing guide for details on how to get started. Please adhere to Fastify's Code of Conduct when contributing.

License

Licensed under MIT.