release-it-action

Runs release-it as a GitHub Action, with handling for semantic releases and protected branches. 📤

release-it is a great tool for releasing packages. But running it in CI takes more work than npx release-it. You need to set up Git and npm first. You probably want safe handling for consecutive branch pushes during your release flow. And if things go wrong, you want informative error reporting to explain what happened.

This action handles all of that for you.

Each time it runs, the action:

1. Sets up the Git user for release commits
2. Finishes any earlier release that didn't make it to npm or GitHub releases, then stops
3. Stops if should-semantic-release says there's nothing to release
4. Runs npx release-it --verbose

It also adds in safe handling for common corner cases such as npm being slow to recognize new versions.

Run JoshuaKGoldberg/release-it-action in a GitHub workflow after building your code:

concurrency:
  group: ${{ github.workflow }}

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          ref: main
          token: ${{ secrets.ACCESS_TOKEN }}
      - run: npm ci
      - run: npm run build
      - env:
          GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}
        uses: JoshuaKGoldberg/release-it-action@v0.6.4

name: Release

on:
  push:
    branches:
      - main

permissions:
  contents: read
  id-token: write

Publishing to npm uses npm's Trusted Publishing, which needs the id-token: write permission and this workflow added as a trusted publisher for your package on npm.

It's strongly recommended to have release-it push before it publishes to npm. Then if a newer push wins the race, nothing gets published. It also lets step 2 finish any release that fails to publish.

{
	"git": {
		"pushArgs": ["--follow-tags", "--atomic"]
	},
	"hooks": {
		"after:git:release": "npm publish${isPreRelease ? ' --tag ' + (preReleaseId || 'next') : ''}"
	},
	"npm": {
		"publish": false
	}
}

Prereleases publish under their own dist-tag, such as beta for 1.2.0-beta.0 or next for 1.2.0-0, since newer versions of npm require a --tag for them. Stable releases leave out --tag so that newer versions of npm can refuse to move latest back to an older version. Step 2 skips release-it's npm authentication checks itself, since they don't work with Trusted Publishing.

Tip: releasing from a maintenance branch? Set "tag" under "npm" to that branch's dist-tag, which step 2 also uses, and change the hook to npm publish --tag ${npm.tag}.

If you set skip-npm-publish, leave out this config's after:git:release hook, since it would still publish.

release-it-action can be installed as a dependency that exports a releaseItAction function:

npm i release-it-action

import { releaseItAction } from "release-it-action";

await releaseItAction({
	githubToken: process.env.GITHUB_TOKEN,
	gitUserEmail: "your@email.com",
	gitUserName: "YourUsername",
	owner: "YourUsername",
	releaseItArgs: "--preRelease=beta",
	repo: "your-repository",
});

The Node API doesn't read action inputs or change process.env. It passes githubToken to release-it as the GITHUB_TOKEN environment variable. Other environment variables still apply, such as GITHUB_API_URL for its GitHub API requests.

The action needs the latest commit of your release branch. The concurrency group keeps later runs from missing earlier release commits.

release-it pushes with the credentials saved by actions/checkout, which default to the workflow's GITHUB_TOKEN. Pushes made with GITHUB_TOKEN don't trigger workflows. Checking out with your PAT lets the release commit start its own run, which is how the next section's recovery gets to happen on its own. It also makes the push come from your PAT's user, which matters for ruleset bypass lists.

Sometimes a release gets pushed to GitHub without making it to npm. The next run publishes that version without making a new commit or tag. It also creates the GitHub release if it's missing.

This only works if the version's Git tag is on the latest commit. Otherwise the action fails until you publish that version yourself, or bump the version manually if npm won't accept it again.

The check assumes your package belongs on npm. If it doesn't, set skip-npm-publish or mark the package as "private": true. Otherwise every push fails as an unpublished version.

A release can also get pushed without its GitHub release, such as when creating the release fails after the npm publish. If that version's Git tag is on the latest commit, the next run creates the missing GitHub release. This only happens when github.release is true in your .release-it.json or package.json's "release-it".

Two pushes close together can start two release runs. The first run's push fails because the branch has a newer commit. The action exits without failing so the newer run can do the release.

This relies on the recommended config pushing before publishing.

The bypass-branch-protections option is not recommended.

Some repositories have strict older branch protections that block pushes to main. This option lets release-it push anyway. Use GitHub's newer repository rulesets instead.

GitHub doesn't have an API to turn off a branch protection rule. Deleting and recreating it is the only way at time of writing. If you know of one, please do file an issue!

The bypass-branch-rulesets option is not recommended.

Rulesets can let specific users or apps bypass them. Add the user or app behind your github-token to the ruleset's bypass list instead. If you can't, this option disables the branch's repository rulesets while release-it runs. Organization rulesets aren't changed.

See .github/CONTRIBUTING.md, then .github/DEVELOPMENT.md. Thanks! 📤

Josh Goldberg ✨ 💻 🖋 📖 🤔 🚇 🚧 📆 🔧 🐛 ⚠️

Navin Moorthy 🔧

markehvn 🔧

michael faith 🐛 💻

💝 This package was templated with create-typescript-app using the Bingo engine.