semantic-release-github-pr

semantic-release-github-pr

Preview the semantic release notes that would result from merging a Github PR.

This semantic-release plugin will post a Github PR comment with a preview of the release that would result from merging.

Install

npm install -D semantic-release semantic-release-github-pr

Usage

npx semantic-release-github-pr

It helps to think about semantic-release-github-pr as a variation on semantic-release's default behavior, using the latter's plugin system to modify some behaviors:

• If a new release would result from running semantic-release, instead of publishing a new release of a package, it posts a comment with the changelog to matching Github PRs.

• It posts a static message when there's no release (for clarity).

• It cleans up any PR comments it previously made (to keep from flooding PRs or leaving outdated information).

Which PRs get a comment?

A PR gets a comment if:

• The PR's from branch matches the current branch (that this plugin is being run on).

  To cover multiple CI scenarios (see below), either of:

  • The PR's test merge commit matches the current branch's git HEAD.
  • The PR and the current branch have the same git HEAD.

• The PR's base branch matches master (default) unless otherwise configured via the baseBranch option.

Configuration

It is assumed the user is already fully familiar with semantic-release and its workflow.

Github

Github authentication must be configured, exactly the same as for semantic-relase's default @semantic-release/github plugin. PR comments will be posted by the associated GitHub user.

Release config

It's possible to configure the expected base branch when matching a PR via a baseBranch option set in the release config.

E.g., in a package.json release config:

{
  "release": {
    "baseBranch": "staging"
  }
}

CI

This plugin is best used with a CI build process to fully automate the posting of comments in Github PRs. Ideally, it should run whenever a PR is opened/updated.

Travis

To only run when necessary, we use the $TRAVIS_PULL_REQUEST environment variable to detect whether the build is a "pull request build".

after_success:
  - "[[ $TRAVIS_PULL_REQUEST != 'false' ]] && npx semantic-release-github-pr || exit 0"

CircleCI

To run only when necessary, we use the $CI_PULL_REQUEST environment variable to detect whether the build has a corresponding pull request.

Unfortunately, CircleCI only supports building on push, not when a PR is created. This limits the usefulness of the plugin somewhat, as a build will have to be triggered manually after a PR is opened for the changelog to post.

post:
  - "[[ $CI_PULL_REQUEST != '' ]] && npx semantic-release-github-pr || exit 0"