jefflinse/pr-semver-bump

A GitHub Action to bump and tag a new semantic version when a pull request is merged.

pr-semver-bump

A GitHub Action to bump and tag a new semantic version when a pull request is merged.

A typical workflow using this action is:

1. A developer creates a pull request.
2. The nature of the next version is discussed as part of a code review. A specific tag is applied to the pull request indicating the nature of the changes (e.g. "major", "minor", or "patch").
3. Upon merging the pull request, a new semantic version is tagged automatically. The version number and release notes are determined using the pull request's metadata.

Many inputs are customizable and the outputs can be used in downstream steps or jobs. See the full example.

Motivation

Most version bumping workflows rely on the presense of substrings in commit messages to determine which version part to change (major, minor, or patch). This is often clunky and error-prone.

This action shifts that responsibility to the pull request level, allowing developers to specify the next release version using a pull request label and enter release notes directly in the description. These aspects of the release can be discussed alongside the actual code changes.

Usage

pr-semver-bump runs in one of two modes: validate and bump.

Use validate mode as a merge gate for pull requests to ensure they contain the necessary metadata for your next release:

name: Release Info
on:
  pull_request:
    types: [labeled, unlabeled, opened, edited, reopened, synchronize, ready_for_review]
jobs:
  check-pr:
    name: Validate Release Label and Notes
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: jefflinse/[email protected]
        name: Validate Pull Request Metadata
        with:
          mode: validate
          repo-token: ${{ secrets.GITHUB_TOKEN }}

Use bump mode to tag a new release after a pull request actually merges, using that metadata:

name: Main CI
on:
  push:
    branches:
      - main
jobs:
  bump-tag-version:
    name: Bump and Tag Version
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: jefflinse/[email protected]
        name: Bump and Tag Version
        with:
          mode: bump
          repo-token: ${{ secrets.GITHUB_TOKEN }}

The action will fail (in either mode) if any of the following are true:

• the pull request is not labeled with an appropriate release label;
• the pull request is labeled with more than one release label;
• require-release-info is true, and no release info is found in the pull request description.

Inputs

Inputs can be used to customize the behavior of the action in both modes.

Name	Description
mode	Required. validate or bump.
repo-token	Required. The GITHUB_TOKEN for the repo. Needed for fetching pull request data and tagging new releases.
major-label	The name of the label that indicates the pull request should result in a major version bump. Default: 'major release'.
minor-label	The name of the label that indicates the pull request should result in a minor version bump. Default: 'minor release'.
patch-label	The name of the label that indicates the pull request should result in a patch version bump. Default: 'patch release'.
noop-labels	The list of label names that indicates the pull request should not result in a updated version bump. Default: ''.
require-release-notes	Whether or not release notes are required.
release-notes-prefix	If defined, constrains release notes to any text appearing after a line matching this pattern in the pull request body. By default, release notes start at the beginning of the pull request description.
release-notes-suffix	If defined, constrains release notes to any text appearing before a line matching this pattern in the pull request body. By default, release notes end at the end of the pull request description.
with-v	If true, newly tagged versions will be prefixed with 'v', e.g. 'v1.2.3'.
base-branch	Whether or not to only consider version tags on the base branch in the pull request.

Using Custom Label Names

By default, the action expects pull requests to be labeled with one of the following labels to indicate the nature of the release: major release, minor release, or patch release.

You can specify your own labels instead. For example, if you always use minor releases for features and patch releases for bugs, you might want:

uses: jefflinse/[email protected]
name: Validate PR Metadata
with:
  mode: validate
  repo-token: ${{ secrets.GITHUB_TOKEN }}
  minor-label: new-feature
  patch-label: bug-fix
  noop-labels:
    - documentation change

Requiring Release Notes

Setting require-release-notes: true in your workflow configuration will require that some sort of release notes be present. By default, the entire pull request description is used as release notes.

uses: jefflinse/[email protected]
name: Validate PR Metadata
with:
  mode: validate
  repo-token: ${{ secrets.GITHUB_TOKEN }}
  require-release-notes: true

Constraining Release Notes

By default, the entire pull request description is used as the release notes. If you want to constrain the release notes to just a subset of the description, you can define release-notes-prefix and/or release-notes-suffix as bounding patterns for the release notes. Lines matching these patterns frame the desired release notes. Any text appearing before the prefix pattern or after the suffix pattern will be ignored.

uses: jefflinse/[email protected]
  name: Validate PR Metadata
  with:
    mode: validate
    repo-token: ${{ secrets.GITHUB_TOKEN }}
    release-notes-prefix: -- begin release notes --
    release-notes-suffix: -- end release notes --

With the above configuration, a pull request description might look something like this:

Summary

This fixs bugs in the thing that isn't working properly.

-- begin release notes --

Multiple bug fixes

• fixes the part where the thing was wrong
• resolves the situation with the problem

-- end release notes --

Additional Info

This is all very important additional info.

and the resulting release notes would contain:

Multiple bug fixes

• fixes the part where the thing was wrong
• resolves the situation with the problem

Outputs

The following outputs are available (in both modes):

Name	Description
old-version	The version before bumping.
version	The version after bumping. Not provided when skipped.
release-notes	Release notes found in the pull request description. Not provided when skipped.
skipped	Indicator set to true if the version bump was skipped.

Permissions

The following workflow permissions are required by this action. Depending on your situation these may need to be set explicitly. See GitHub's documentation for more details.

Scope	Permission
contents	write
issues	read
pull-requests	read

Full Example

Create a validation workflow to run whenever a pull request is created or updated. All optional inputs are explicitly set to their default values in the configuration below.

.github/workflows/pr.yml:

name: Release Info
on:
  pull_request:
    types: [labeled, unlabeled, opened, edited, reopened, synchronize, ready_for_review]
jobs:
  check-pr:
    name: Validate Release Label and Notes
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: jefflinse/[email protected]
        name: Validate Pull Request Metadata
        with:
          mode: validate
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          major-label: major release
          minor-label: minor release
          patch-label: patch release
          noop-labels:
            - documentation change
          require-release-notes: true
          release-notes-prefix: ''
          release-notes-suffix: ''
          with-v: false
          base-branch: false

Create a CI workflow to run whenever a pull request is merged. All optional inputs are explicitly set to their default values in the configuration below.

.github/workflows/ci.yml:

name: Main CI
on:
  push:
    branches:
      - main
jobs:
  bump-tag-version:
    name: Bump and Tag Version
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: jefflinse/[email protected]
        name: Bump and Tag Version
        with:
          mode: bump
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          major-label: major release
          minor-label: minor release
          patch-label: patch release
          noop-labels:
            - documentation change
          require-release-notes: true
          release-notes-prefix: ''
          release-notes-suffix: ''
          with-v: false
          base-branch: false

Contributing

This project is actively maintained. Please open an issue if you find a bug, or better yet, submit a pull request :)

Building

This is a Node.js project. Make sure you have Node and NPM installed, then:

Install dependencies:

npm i

Verify your changes:

npm run all

pr-semver-bump's Issues

Add Support for handling rebase merges

A rebase merge doesn't change the commit messages when it is applied onto the branch.
The current code only looks at the commit message to try and determine the Pull Request, so it will fail if the merge was a rebase merge.

It would be nice if all 3 types of merge strategies were support.

noop-labels not working

Noob labels don't seem to work, config:

            - uses: jefflinse/[email protected]
              name: labels
              with:
                  mode: validate
                  repo-token: ${{ secrets.GITHUB_TOKEN }}
                  major-label: major
                  minor-label: minor
                  noop-labels:
                    - documentation change
                  patch-label: patch

Results in a:
The workflow is not valid. .github/workflows/pull_request.yaml (Line: 110, Col: 21): A sequence was not expected

When I remove noop-labels it works fine.

The default in action.yaml is also an empty string, so something is up.

Edit: it works as a string.

`set-output` command is deprecated and will be disabled soon

Hi,

According to this the set-output command is deprecated and I am getting warning about it in the action output.
Are there any plans to replace the set-output command with the appropriate environment file as mentioned in the link?

getCurrentVersion() should fetch and paginate all results

Summary

getCurrentVersion() in version.js currently fetches only the first 30 matching refs (default as per the oktokit API), but should actually be fetching all matching refs using pagination. See here.

No tag created during rebase-and-merge

When rebasing a PR merge, no tag is created and the following error appears in the logs:

head commit doesn't look like a PR merge, skipping version bumping and tagging

Action should create a full release, not just an annotated tag

The action should create a full GitHub Release when run, not just an annotated tag. This will eliminate the need to manually create a full release from an existing tag via the web UI or other means. It will also open up the ability to support release archives.

To maintain compatibility, this could be toggled with a flag such as create-release which defaults to false.

Getting error saying Node.js 12 are deprecated

Hi there, sorry a bit of a noob in GitHub actions so asking it here:

I get the following error when I run the action:
Error: failed to fetch data for PR #53: Not Found
And the warning:
Node.js 12 actions are deprecated. Please update the following actions to use Node.js 16: jefflinse/pr-semver-bump@v1. For more information see: https://github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12/.
I'm using ubuntu-latest to run, see yml:

jobs:
validate-pr:
name: Validate PR Open
runs-on: ubuntu-latest

  outputs:
    version: ${{steps.tag-version.outputs.version}}
  
  steps:
    - name: Checkout repo
      uses: actions/checkout@v3
      with:
        fetch-depth: 0          

    - name: Validate Pull Request Metadata
      id: tag-version
      uses: jefflinse/pr-semver-bump@v1
      with:
        mode: validate
        repo-token: ${{ secrets.GH_TOKEN }}
        major-label: major
        minor-label: minor
        patch-label: patch
        require-release-notes: true
        release-notes-prefix: ''
        release-notes-suffix: ''
        with-v: false

I was working before, but today it doesn't work anymore. Do you perhaps know how to fix it? Thanks in advance!

Error on version bump: Resource not accessible by integration

I'm getting the error unexpected error: Resource not accessible by integration when running the version bump here.

Here's the definition for the failing workflow.

Contributing instructions

It would be helpful to have a CONTRIBUTING.md in the root with information on how to participate in the project. At the very least, details on build/test tools and processes would be extremely appreciated.

Bump fails when run on the very first commit in a repository

If a new repository is based on a template containing a workflow with this action, it may end up being run on the very first commit. However, since that commit is not based on a PR it causes the action to fail. It would be nice if it could instead emit a default version number or at least have the option of doing so. Perhaps it could be configurable: some option that does nothing if unset or emits the specified value if run on the first commit.

Add support for merging PRs without tagging a new version

Instead of always requiring a GitHub version tag (e.g. "major", "minor", "patch", etc) on every pull request, it should be possible for the author to indicate that no new version is to result from merging the pull request.

Proposal

Add a noop-labels configuration variable that accepts a list of label names that, when any are applied to the pull request, will result in no new version being tagged.
a. It is valid to assign more than one label in the noop-labels group to a pull request.
b. It is invalid to assign any label from the noop-labels group and to also assign a label defined by major-label, minor-label, or patch-label.

For example, using the configuration below, users could then label a pull request with documentation change or no new version (or both), causing the pr-semver-bump workflow to complete successfully without tagging any new version.

with:
  noop-labels:
    - documentation change
    - no new version

Support Squash Merge as valid Merge request commit

Currently if you squash merge your PR the semver bump will fail, as it can't determine the merge request.
This is because it's looking at the merge request commit message to parse out the merge request.

The error you will receive is
head commit doesn't look like a PR merge, skipping version bumping and tagging

Squash merging of large PR's is a best practice and I would like to request this support be added.

Unit tests don't run in pull requests from forked repos

The unit test workflow is required for merging a pull request, but the action hangs when a pull request is opened from a fork.

Ability to use git operations rather than github api

I ideally want to use pushing a new tag as a trigger for a second part of my release code. I can currently do that by using a personal access token, but there is a potential second option outlined here. In short, by creating a deploy key with write access, one can push changes and trigger workflows.

I've explained in a little more detail in my fork of this project https://github.com/Spatial-Quotient/pr-semver-bump#adds-use-ssh-option

Would you consider a PR to add this as an option? I'd love to be able to avoid using a personal access token for my use-case :)

Reference Update Failed on bump

See below screenshot:

Below is the workflow file that triggers the error:

name: AutoTag SemVer Git Tag
on:
  push:
    branches:
      - main
  workflow_call:
    inputs:
      continue-on-error:
        type: boolean
        required: false
        default: false

jobs:
  bump-tag-version:
    name: Bump and Tag Version
    runs-on: ubuntu-latest
    continue-on-error: ${{inputs.continue-on-error}}
    permissions:
      contents: write
      issues: read
      pull-requests: read
    steps:
      - uses: jefflinse/pr-semver-bump@v1
        name: Bump and Tag Version
        with:
          mode: bump
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          require-release-notes: false
          with-v: true
          base-branch: true
          
      - name: Warn on Failure
        if: failure()
        uses: actions/github-script@v6
        with:
          script: |
            core.warning(`Semantic Version Pip Failed! Check your PR Labels!`);

The explicit permissions are being granted by the calling workflow.

Happy to provide additional information as requested.

Add support for additional release types: automation, documentation

Some merges to main are from things like dependabot merging dependency change to main, or from developers merging documentation changes that don't actually affect a codebase. Should consider supporting these scenarios in order to better determine how to proceed in such cases.

Outputs should include individual version parts

It would be useful for the action outputs to include the version parts as individual output variables. Ideally this should include:

• old-major-
• old-minor-
• old-patch-
• major-version
• minor-version
• patch-version

This would allow downstream tasks and jobs that require version information to be able to obtain it independent of whether the v prefix was used for the tag and release.

@actions/github is deprecated

@actions/github has been deprecated and should be replaced with @actions/github-script.