semantic-release-github-pr
![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)
Preview the semantic release notes that would result from merging a Github PR.
![image](https://user-images.githubusercontent.com/356320/33625928-257bc906-d9c7-11e7-9adb-de85726952eb.png)
This set of semantic-release
plugins will post a Github PR comment with a preview of the release that would result from merging.
Install
npm install -D semantic-release-github-pr
Usage
npx semantic-release-github-pr
It helps to think about semantic-releaase-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 to npm
, it posts a comment with the changelog to matching Github PRs.
-
It posts a static message when there's no release (for clarity).
-
At the beginning of each run, it cleans up any PR comments it previously made (to keep from flooding PRs or leaving outdated information).
A PR gets a comment if:
-
The PR's "from" branch matches the current branch (that this command is being run against).
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 the githubPr.branch
configuration option is set.
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.
Release config
It's possible to configure the expected base branch when matching a PR.
E.g., package.json
:
{
"release": {
"githubPr": {
"branch": "staging"
}
}
}
Other ways of configuring branch
.
Advanced
Due to limitations in how plugins may be composed, semantic-release-github-pr
must unfortunately hard-code the analyzeCommits
plugin (see discussion here).
Users may still want to define a custom analyzeCommits
plugin, or want to pass options to the default analyzeCommits
plugin. To work around this problem, set the desired analyzeCommits
configuration in the release plugin config inside the githubPr
key instead.
E.g., package.json
:
{
"release": {
"githubPr": {
"analyzeCommits": "myCommitsAnalyzer"
}
}
}
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"
Advanced
Running semantic-release-github-pr
is equivalent to running semantic-release
with the following configuration (as encapsulated in the semantic-release-github-pr
command):
{
"release": {
"analyzeCommits": "semantic-release-github-pr",
"publish": "semantic-release-github-pr",
"verifyConditions": [
"@semantic-release/github",
"semantic-release-github-pr"
]
}
}
verifyConditions
Used as a hook for cleaning up previous changelog PR comments made by the publish
plugin, keeping it from flooding a PR with (eventually stale) changelog comments over time.
It's recommended to pair this package's verifyConditions
with that of @semantic-release/github
.
analyzeCommits
Used as a hook to create a "no release" comment on a matching PR, if semantic-release
determines that there's no new version. Doesn't actually analyze commits itself, but decorates an analyzeCommits
implementation (@semantic-release/commit-analyzer
by default).
See the Release config
section for how to configure a custom analyzeCommits
plugin and/or set options.
publish
Creates a comment on matching PRs with the changelog for the release that would result from merging.