uppt #

A composite GitHub Action that turns conventional commits into a draft release PR, tags the PR on merge, and stages publishing to npm via OIDC trusted publishing.

The aim of uppt is a simple, secure release workflow that doesn't require tokens or trusting a third-party GitHub App. It was extracted from scripts used in nuxt/nuxt.

Getting started #

1. Set up trusted publishing on npmjs.com. Visit https://npmjs.com/package/<package-name>/access and add a trusted publisher pointing at your repo and the release.yml workflow, with the npm stage publish permission chip and 'Environment name' set to npm. In a monorepo, repeat once per published package.

   The package must already exist on npm; for a brand-new package, npx setup-trusted-publishing (docs) publishes a 0.0.0 stub you can attach the entry to.

2. Create a GitHub environment named npm, with whatever restrictions you like (such as required approvals). If you limit which refs can deploy to it, allow both v* and release-* tags.

   Screenshot

   

3. Allow GitHub Actions to create pull requests: check Allow GitHub Actions to create and approve pull requests under Settings → Actions → General → Workflow permissions. Without it, uppt/pr won't be able to open the release PR.

4. Add the workflow below as .github/workflows/release.yml, and you're done!

name: release

on:
  push:
    # release/v* picks up hand edits to an open release PR
    branches: [main, 'release/v*']
  pull_request:
    types: [closed]
    branches: [main]
  # merged release PRs, publish reruns, and prereleases all arrive here
  workflow_dispatch:
    inputs:
      prerelease:
        description: 'Cut a prerelease instead of a normal release, e.g. `beta`, `rc`, or `0`'
        required: false
        default: ''
      npm-tag:
        description: 'npm dist-tag to publish to. Set by uppt/release for maintenance lines; leave blank otherwise'
        required: false
        default: ''

permissions: {}

jobs:
  # open or update a draft release PR from conventional commits
  pr:
    if: |
      !github.event.repository.fork
      && (
        (
          github.event_name == 'push'
          && (
            github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
            || startsWith(github.ref, 'refs/heads/release/v')
          )
        ) || (
          github.event_name == 'workflow_dispatch'
          && !startsWith(github.ref, 'refs/tags/')
        )
      )
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: danielroe/uppt/pr@6ec27140623aa835e362f866d8ab0018ab057f4d # v0.6.11
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          prerelease: ${{ inputs.prerelease }}

  # release PR merged: tag it, cut a GitHub release, dispatch the publish run
  release:
    if: |
      github.event_name == 'pull_request'
      && github.event.pull_request.merged == true
      && startsWith(github.event.pull_request.head.ref, 'release/v')
      && github.event.pull_request.head.repo.full_name == github.repository
      && !github.event.repository.fork
    runs-on: ubuntu-latest
    concurrency:
      group: release-${{ github.event.pull_request.number }}
      cancel-in-progress: false
    permissions:
      contents: write
      actions: write
    steps:
      - uses: danielroe/uppt/release@6ec27140623aa835e362f866d8ab0018ab057f4d # v0.6.11
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

  # the chained dispatch lands here on the vX.Y.Z tag; build the tarball(s)
  pack:
    if: github.event_name == 'workflow_dispatch' && startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-latest
    concurrency:
      group: pack-${{ github.ref }}
      cancel-in-progress: false
    permissions: {}
    outputs:
      files: ${{ steps.pack.outputs.files }}
    steps:
      - id: pack
        uses: danielroe/uppt/pack@6ec27140623aa835e362f866d8ab0018ab057f4d # v0.6.11

  # stage the prebuilt tarball(s) to npm via OIDC
  publish:
    if: |
      github.event_name == 'workflow_dispatch'
      && startsWith(github.ref, 'refs/tags/v')
      && needs.pack.outputs.files != '[]'
    needs: pack
    runs-on: ubuntu-latest
    concurrency:
      group: publish-${{ github.ref }}
      cancel-in-progress: false
    permissions:
      id-token: write
    environment: npm
    steps:
      - uses: danielroe/uppt/publish@6ec27140623aa835e362f866d8ab0018ab057f4d # v0.6.11
        with:
          files: ${{ needs.pack.outputs.files }}
          npm-tag: ${{ inputs.npm-tag }}

How it works #

1. uppt/pr - on every push to the default branch, parses conventional commits since the latest tag, decides the bump (major/minor/patch), pushes a release/vX.Y.Z branch with the version bump, and opens or updates a draft release PR (closing any superseded ones).
2. uppt/release - when the release PR is merged, tags the squash commit, creates a GitHub Release from the PR body, and dispatches the publish workflow on the new tag.
3. uppt/pack - installs dependencies, runs pnpm pack (if pnpm-lock.yaml exists) or npm pack, and uploads the tarball(s) as a workflow artifact, exposing a files output.
4. uppt/publish - downloads the artifact and runs npm stage publish with OIDC. You then approve the staged version on npmjs.com.

Inputs #

All subactions take a node-version input (default 24; uppt needs --experimental-strip-types, so Node 22.6+ also works) and, where applicable, a checkout input (true by default; set to false if the caller has already checked out the right ref - fetch-depth: 0 for pr, on the release PR's base for a release/v* push, the merge commit for release, the tag for pack).

Lifecycle scripts #

uppt runs your package's lifecycle scripts at one specific point and skips them everywhere else, so the runner that produces the tarball executes as little third-party code as possible:

• Install (in uppt/pack): runs with --ignore-scripts. Dependencies' postinstall hooks and your own prepare do not fire; this is why a compromised transitive dependency can't run code on the publish runner. If your build genuinely needs a dependency's postinstall, set install: false and install yourself.
• Pack (in uppt/pack): prepack, prepare, and postpack run. This is where your build belongs.
• Publish (in uppt/publish): nothing runs, including prepublishOnly. Move any prepublishOnly logic into prepack.

Prereleases #

To cut a prerelease, run the release workflow from your default branch with the prerelease input set:

gh workflow run release.yml -f prerelease=beta

From 4.5.2, if there's been a breaking change this will open a PR for 5.0.0-beta.0. Running it again will produce 5.0.0-beta.1. A different identifier will reset the counter (5.0.0-rc.0), or a bare number produces the 5.0.0-0 style. It's one-shot: the next ordinary push opens a separate PR for a stable release (e.g. 5.0.0). Prerelease and stable release PRs are tracked independently, so an ordinary push won't close an open prerelease PR.

Prereleases don't take the latest dist-tag: uppt/publish derives the tag from the version being published, so 5.0.0-beta.0 is staged as beta, 5.0.0-rc.1 as rc, and 5.0.0-0 as next (a bare number has no name to use). Set npm-tag on uppt/publish to override; it's also required if a tarball's filename carries no parseable version, as uppt fails rather than defaulting to latest.

Maintenance releases #

To release from an older line, run uppt/pr on that branch with base-branch set to it (3.x), and add the branch to the workflow's push and pull_request triggers.

Nothing else to configure: a release PR merged into a branch other than the default one can't be the newest line, so uppt publishes it to <major>x (3.9.1 → 3x) instead of latest, and doesn't mark the GitHub release as the repo's "Latest". The derived tag is passed to the publish workflow as its npm-tag input, which the starter workflow already forwards to uppt/publish.

If your line uses a different dist-tag (legacy, v3-latest), or the release spans majors so there's no single <major>x to derive, set npm-tag on uppt/release:

- uses: danielroe/uppt/release@6ec27140623aa835e362f866d8ab0018ab057f4d # v0.6.11
  with:
    npm-tag: legacy

It overrides the derivation, applies to every tarball in the run, and any value other than latest also keeps the GitHub release out of the "Latest" slot.

Nightly releases #

uppt can also publish a nightly build of every push to a branch, under a separate package name (@nuxt/test-utils → @nuxt/test-utils-nightly). Nightlies skip the release PR and staging: they publish straight to npm via OIDC, so add a trusted publisher for each nightly package pointing at the workflow below, with 'Environment name' set to nightly (no npm stage publish permission needed). As with stable releases, each nightly package must already exist on npm before you can attach a trusted publisher to it, so publish a stub first (for example with npx setup-trusted-publishing).

Create a matching nightly GitHub environment and limit its deployment branches to the branch(es) you publish nightlies from (e.g. main). Without approvals or staging, this is what stops a workflow run on any other ref from publishing.

name: nightly

on:
  push:
    branches: [main]

permissions: {}

jobs:
  pack:
    if: '!github.event.repository.fork'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      files: ${{ steps.pack.outputs.files }}
    steps:
      - id: pack
        uses: danielroe/uppt/pack@6ec27140623aa835e362f866d8ab0018ab057f4d # v0.6.11
        with:
          nightly: true

  publish:
    needs: pack
    runs-on: ubuntu-latest
    concurrency:
      group: nightly-${{ github.ref }}
      cancel-in-progress: false
    permissions:
      id-token: write
    environment: nightly
    steps:
      - uses: danielroe/uppt/publish@6ec27140623aa835e362f866d8ab0018ab057f4d # v0.6.11
        with:
          nightly: true
          files: ${{ needs.pack.outputs.files }}

uppt/pack rewrites each package before packing it:

• Name: <name>-nightly. Set nightly-suffix to use something else (-edge).
• Version: <version>-<YYMMDDHHmm>-<sha>, e.g. 3.20.1-2605140905-a1b2c3d. <version> is the X.Y.Z part of the version in package.json, the timestamp is the HEAD commit's date in UTC, and <sha> is its 7-character short hash. Newer commits always sort higher. Publishing a commit whose nightly is already on npm (for example, a re-run) logs a warning and skips the package rather than failing.
• Workspace dependencies: in a monorepo (pass the same packages input), dependencies between listed packages become npm:<name>-nightly@<version>, so each nightly installs the other nightlies from the same commit.
• External nightlies: nightly-aliases points dependencies on packages from other repos at their own nightlies.
• Bins: every command gains a -nightly copy, plus one named after the package, so npx <name>-nightly works.

- uses: danielroe/uppt/pack@6ec27140623aa835e362f866d8ab0018ab057f4d # v0.6.11
  with:
    nightly: true
    packages: packages/*
    nightly-aliases: |
      nuxi
      @nuxt/cli: @nuxt/cli-nightly@5x

A bare name aliases to npm:<name>-nightly@latest. Nightlies publish to the latest dist-tag of the nightly package; set npm-tag on uppt/publish to publish a branch to another tag (5x).

Monorepo support #

For a lockstep monorepo (where every publishable package shares a single version and one vX.Y.Z tag), pass the same packages: input to uppt/pr, uppt/release, and uppt/pack:

        with:
          # ...
          packages: |
            packages/*
            !packages/playground

Each line is a directory path or glob; !-prefixed entries are excluded; workspaces with "private": true are silently skipped.

Every listed package must agree on a single semver version. The root package.json#version is only bumped when it already matches, so a 0.0.0 or absent root version is left untouched.

Independent versioning (experimental) #

If lockstep is the wrong shape (one package on 0.8.0, another on 0.2.1), set mode: independent alongside packages: on uppt/pr and uppt/release, and each package will advance on its own cadence.

Commits are routed to packages by conventional-commit scope. By default a package claims the last segment of its name (feat(kit): bumps @nuxt/kit); override or alias this with scopes: on uppt/pr:

          scopes: |
            @nuxt/kit: kit nuxt-kit
            @nuxt/schema: schema

A comma-separated scope (fix(fontaine,fontless):) bumps every package it names. Commits with no scope, or an unmatched scope, do not bump anything.

You get a single release/<base>-pending PR with a section per package. On merge, uppt tags each released package as <name>@X.Y.Z, creates one GitHub release on a release-YYYY-MM-DD coordination tag, and dispatches the publish workflow with a releases payload naming the packages to pack and stage. They go live together when you approve them on npmjs.com.

The workflow needs a few changes on top of the lockstep setup: a releases dispatch input, mode: independent, a looser release/ head-ref guard, and job conditions that accept the coordination tag.

name: release

on:
  push:
    branches: [main]
  pull_request:
    types: [closed]
    branches: [main]
  workflow_dispatch:
    inputs:
      prerelease:
        description: 'Cut a prerelease instead of a normal release, e.g. `beta`, `rc`, or `0`'
        required: false
        default: ''
      npm-tag:
        description: 'npm dist-tag to publish to. Set by uppt/release for maintenance lines; leave blank otherwise'
        required: false
        default: ''
      releases:
        description: 'Publish payload emitted by uppt/release; leave empty when rerunning a publish by hand'
        required: false
        default: ''

permissions: {}

jobs:
  pr:
    if: |
      !github.event.repository.fork
      && (
        (
          github.event_name == 'push'
          && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
        ) || (
          github.event_name == 'workflow_dispatch'
          && !startsWith(github.ref, 'refs/tags/')
        )
      )
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: danielroe/uppt/pr@6ec27140623aa835e362f866d8ab0018ab057f4d # v0.6.11
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          prerelease: ${{ inputs.prerelease }}
          mode: independent
          packages: |
            packages/*

  release:
    if: |
      github.event_name == 'pull_request'
      && github.event.pull_request.merged == true
      && startsWith(github.event.pull_request.head.ref, 'release/')
      && github.event.pull_request.head.repo.full_name == github.repository
      && !github.event.repository.fork
    runs-on: ubuntu-latest
    concurrency:
      group: release-${{ github.event.pull_request.number }}
      cancel-in-progress: false
    permissions:
      contents: write
      actions: write
    steps:
      - uses: danielroe/uppt/release@6ec27140623aa835e362f866d8ab0018ab057f4d # v0.6.11
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          mode: independent
          packages: |
            packages/*

  pack:
    if: |
      github.event_name == 'workflow_dispatch'
      && (startsWith(github.ref, 'refs/tags/v') || startsWith(github.ref, 'refs/tags/release-'))
    runs-on: ubuntu-latest
    concurrency:
      group: pack-${{ github.ref }}
      cancel-in-progress: false
    permissions: {}
    outputs:
      files: ${{ steps.pack.outputs.files }}
    steps:
      - id: pack
        uses: danielroe/uppt/pack@6ec27140623aa835e362f866d8ab0018ab057f4d # v0.6.11
        with:
          releases: ${{ inputs.releases }}
          packages: |
            packages/*

  publish:
    if: |
      github.event_name == 'workflow_dispatch'
      && (startsWith(github.ref, 'refs/tags/v') || startsWith(github.ref, 'refs/tags/release-'))
      && needs.pack.outputs.files != '[]'
    needs: pack
    runs-on: ubuntu-latest
    concurrency:
      group: publish-${{ github.ref }}
      cancel-in-progress: false
    permissions:
      id-token: write
    environment: npm
    steps:
      - uses: danielroe/uppt/publish@6ec27140623aa835e362f866d8ab0018ab057f4d # v0.6.11
        with:
          files: ${{ needs.pack.outputs.files }}
          npm-tag: ${{ inputs.npm-tag }}
          releases: ${{ inputs.releases }}

When releases is empty every action behaves exactly as in lockstep mode, so rerunning a publish by hand on a v* tag still works.

Credits #

Inspired by unjs/changelogen and antfu/changelogithub. You might also want to check out changesets and release-please.

License #

Made with ❤️

Published under MIT License.