🚀 simple-release-action

A simple GitHub Action to automate version bumps, changelogs, and releases using Conventional Commits.

• 📄 Uses conventional-changelog to parse commits, determine the next version, and generate a changelog.
• 🗂️ Supports monorepos and can release multiple packages in a single run.
• 🧩 Flexible and extensible with custom addons for different project types.

See simple-release docs for more details.

Tip

New to Сonventional Сommits? Check out The Complete Guide.

Usage

1. Create .simple-release.json config file with project setup in repository root:

{
  "project": ["@simple-release/pnpm#PnpmWorkspacesProject", {
    "mode": "fixed"
  }]
}

js-config example

You should install the addon package first, then:

import { PnpmWorkspacesProject } from '@simple-release/pnpm'

export const project = new PnpmWorkspacesProject({
  mode: 'fixed'
})

In this example @simple-release/pnpm is used to setup a monorepo project with fixed versioning mode.

Addon will be automatically downloaded and cached by the action when it runs.

You can find other addons in the simple-release repository.

2. Create .github/workflows/release.yml with release workflow, like in the example below:

name: Release
on:
  issue_comment:
    types: [created, deleted]
  push:
    branches:
      - main
jobs:
  check:
    runs-on: ubuntu-latest
    name: Context check
    outputs:
      continue: ${{ steps.check.outputs.continue }}
      workflow: ${{ steps.check.outputs.workflow }}
    steps:
      - name: Checkout the repository
        uses: actions/checkout@v4
      - name: Context check
        id: check
        uses: trigensoftware/simple-release-action@v1
        with:
          workflow: check
          github-token: ${{ secrets.GITHUB_TOKEN }}
  pull-request:
    runs-on: ubuntu-latest
    name: Pull request
    needs: check
    if: needs.check.outputs.workflow == 'pull-request'
    steps:
      - name: Checkout the repository
        uses: actions/checkout@v4
      - name: Create or update pull request
        uses: trigensoftware/simple-release-action@v1
        with:
          workflow: pull-request
          github-token: ${{ secrets.GITHUB_TOKEN }}
  release:
    runs-on: ubuntu-latest
    name: Release
    needs: check
    if: needs.check.outputs.workflow == 'release'
    steps:
      - name: Checkout the repository
        uses: actions/checkout@v4
      - name: Install pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 10
      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: 'pnpm'
          registry-url: 'https://registry.npmjs.org'
      - name: Install dependencies
        run: pnpm install
      - name: Release
        uses: trigensoftware/simple-release-action@v1
        with:
          workflow: release
          github-token: ${{ secrets.GITHUB_TOKEN }}
          npm-token: ${{ secrets.NPM_TOKEN }}

Now every time you push to the main branch, the action will create or update a pull request with a version bump and updated changelog if necessary. When the pull request is merged, it will automatically release the project. Also you can comment on the pull request to pass additional options to simple-release:

!simple-release/set-options

```json
{
  "bump": {
    "prerelease": "alpha"
  }
}
```

Options

workflow

Workflow to run.

• full: create PR with release changes and release on merge (default)
• pull-request: create PR with release changes
• release: run release on release commit
• snapshot: publish a temporary snapshot version
• check: run context check to skip unnecessary runs (e.g. on issue_comment) and determines workflow to run

github-token

GitHub token to authenticate with the GitHub API.

Note

If you want to run workflows on PR created by this action, you need to use a personal access token instead of the default GITHUB_TOKEN.

npm-token

NPM token to authenticate with the NPM registry. Passed to NODE_AUTH_TOKEN env variable.

publish-token

Generic token to use in config file. Passed to PUBLISH_TOKEN env variable.

branch

Branch to store release changes and create pull request from. Defaults to simple-release.

bump-version

Force set specific version.

bump-as

Release type. One of major, minor, patch, or prerelease.

bump-prerelease

Pre-release identifier (e.g., alpha, beta).

bump-snapshot

Snapshot pre-release identifier.

bump-first-release

Whether this is the first release. Accepts true or false.

bump-skip

Skip version bump. Accepts true or false.

bump-by-project

JSON object with per-project bump options for monorepos.

with:
  bump-by-project: '{"pkg-a":{"as":"minor"},"pkg-b":{"skip":true}}'

maintenance-branch

Create maintenance branches for previous major versions. Accepts true or false.

publish-skip

Skip publishing. Accepts true or false.

publish-access

Package access level. One of public or restricted.

publish-tag

Tag for npm publication.