changesets-snapshot

A GitHub Action for publishing snapshot releases when using changesets.

Why

Changesets publish a GitHub action which can be used for the regular changesets flow of Version Packages PR and publishing to NPM.

Unfortunately, the Changesets action doesn't support publishing snapshot releases (yet?), so this action exists to fill that requirement.

Tradeoffs

In order to set up the proper arguments/config for snapshot publishing, this action calls changeset version and changeset publish internally.

This means that, unlike the Changesets action, these commands cannot be overridden entirely. You can provide extra scripts that you want to run ahead of each of the version and publish commands, but the changeset commands will still run as well.

Practically, this means:

• This action can only publish NPM packages. changeset publish eventually calls npm publish, so a project that isn't published with npm won't be able to use this snapshot action.
• This action can only publish to the npmjs.com registry. To ensure auth is set up correctly, this action will overwrite any existing .npmrc files. This means that alternate registry information will be lost (e.g. for publishing to GitHub Packages). We're open to this being a feature though, so create an issue if this is a part of the workflow that you need.

Getting Started

To publish snapshot releases for your package, you need to create a workflow that uses the seek-oss/changesets-snapshot action.

You probably also want to run this workflow manually, rather than on every push, which means configuring it to respond to the workflow_dispatch event.

In this particular example, you will need to provide an NPM token and a GitHub token to the env of the action.

An example workflow might look like:

name: Snapshot

on: workflow_dispatch

jobs:
  release:
    name: Publish snapshot version
    runs-on: ubuntu-latest
    env:
      CI: true
    steps:
      - name: Check out repo
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 20.x

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Publish
        uses: seek-oss/changesets-snapshot@v0
        with:
          pre-publish: pnpm build
        env:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Trusted publishing

To configure a npm token-less workflow, you can enable Trusted publishing on your npm package. Since this requires specifying a single workflow file, you'll need to create a shared release workflow that uses alternate triggers and conditions.

An example workflow might look like:

name: Release

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  release:
    name: Publish latest version
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    env:
      CI: true
    steps:
      - name: Check out repo
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 20.x

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # npm 11.5.1 or later is required
      - name: Install latest npm
        run: npm install -g npm@latest

      - name: Publish to npm
        uses: changesets/action@v1
        with:
          publish: pnpm release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  snapshot:
    name: Publish snapshot version
    if: github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    env:
      CI: true
    steps:
      - name: Check out repo
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 20.x

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      # npm 11.5.1 or later is required
      - name: Install latest npm
        run: npm install -g npm@latest

      - name: Publish
        uses: seek-oss/changesets-snapshot@v0
        with:
          pre-publish: pnpm build
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Advanced triggers

Github actions have many options for deciding whether a workflow should be run.

One example of an alternative flow to the manual run is to run the snapshot release when someone comments a specific phrase on a PR. Polaris has an implementation of this for inspiration, which runs when an authorised user comments /snapit on a PR.

API

Inputs

When running the regular changesets action, you can provide your own scripts for version and publish, which allows you to use custom publishing behaviours instead of the changesets builtin.

This is useful if you are:

• not publishing to the npmjs.com registry or releasing an NPM packge, hence requiring some other publish process
• or, if there are other processes you need to run in conjunction with versioning/publishing.

This action only publishes NPM packages to the npmjs.com registry, but the second point is addressed through the pre- inputs.

pre-version

You can provide a script here that will run before the changeset version command, in case you have any custom versioning requirements that wouldn't be handled by the inbuilt changeset version command.

pre-publish

Perhaps more common, the pre-publish input can be used for processes you want to run before (and only before) the changeset publish occurs.

For example, you might want to use this step to run a build before the publish step runs.

Outputs

The action reports on the outcome of publishing primarily with a notice in the step summary, but also as action outputs.

The action outputs are listed in the action.yml file.