Automatically generate a release, along with a corresponding git tag, for GitHub-hosted source code.semantic-release-github
Automatically generate a release, along with a corresponding git tag, for GitHub-hosted source code.
When you create a new release for your GitHub project, you probably do several of the steps listed below:
- Get a list of all commits to the project that have not been released.
- Determine the appropriate semantic version to use for the release.
- Generate a git tag for the repository on GitHub with that version.
- Publish a GitHub release page with a list of changes in that version.
- Inform people subscribed to GitHub issues, or pull requests, about the release.
semantic-release-github streamlines all those steps into a single command line tool.
semantic-release-github is a command line tool, you can call
semantic-release-github yourself whenever you want, or you can setup your project to automatically call
semantic-release-github after every commit to your repository, or set it up to run on a regular schedule.
This idea, however, is not new.
semantic-release-github was heavily inspired by the work of semantic-release.
Table of Contents
- How to Publish Project to an npm Registry
- Version Selection
- Release Strategies
- Common Issues
- Node Support Policy
- Get a list of unreleased commits using git-raw-commits.
- Detect commit message convention used by a project with conventional-commits-detector.
- Determine appropriate version to release, or whether to release at all, with conventional-recommended-bump.
- Publish a GitHub release using conventional-github-releaser.
- Create an annotated git tag on GitHub.
- Post a comment to GitHub issues closed by changes included in a release.
To install the
semantic-release-github tool for use in your project's release process please run the following command:
yarn add --dev semantic-release-github
Setup the environment variable described in the Required Environment Variable section.
semantic-release-github from within your project's top folder:
To learn how
semantic-release-github can be used to automatically release your project on new changes to your repository, please see the Continuous Integration and Delivery (CID) Setup section below.
How the Release Happens
First step of
semantic-release-github is to get a list of commits made to your project after the latest semantic version tag. If no commits are found, which typically happens if the latest commit in your project is pointed to by a semantic version tag, then
semantic-release-github will exit cleanly and indicate no changes can be released. This ensures you can run the release process multiple times and only release new versions if there are unreleased commits. If unreleased commits are available,
semantic-release-github will proceed to the next step.
Unless you have configured a preset, the convention used by your project will be determined by
conventional-commits-detector. Once we have determined your convention, we pass along the preset package associated with that convention to
conventional-recommended-bump will determine the appropriate version to release. For more information on how versions are determined, please see the Version Selection section below.
Once a recommendation has been provided by
conventional-recommended-bump, we generate a new GitHub release page, with a list of all the changes made since the last version, using the authentication token configured in the Required Environment Variables section below. Creating a GitHub release also creates an annotated git tag (You can retrieve the annotated tag using
Lastly, a comment will be posted to every issue that is referenced in a released commit, informing subscribers to that issue of the recent release and version number.
Required Environment Variable
semantic-release-github to publish a release to GitHub a GitHub personal access token must be setup within your environment with the
repo scope selected.
Environment variable name -
The GitHub personal access token must be associated with an account that has Write permissions on the repository that will be released.
Version selection, the format of the release notes, among other things, are configured through a
conventional-changelog preset package.
For example, to use the ESLint release conventions, first install their preset package along-side
yarn add --dev conventional-changelog-eslint
Then pass the name, minus
conventional-changelog-, of the preset package to
$(yarn bin)/semantic-release-github --preset eslint
If a preset is not provided
semantic-release-github will use
Using HTTP for GitHub
By default all API calls to GitHub are made over HTTPS. To use HTTP set the environment variable
true. Other values, including not setting the environment variable, will cause
semantic-release-github to use HTTPS.
We strongly advise against communicating with GitHub over HTTP, but this option is supported for those cases where configuring SSL for GitHub is not feasible.
Continuous Integration and Delivery (CID) Setup
semantic-release-github relies on a GitHub token, and a package published to the public npm registry,
semantic-release-github works on any GitHub-compatible continuous integration platform.
How to Publish Project to an npm Registry
semantic-release-github has created a release on GitHub, the next step for an
npm package is to publish that package to an
npm-compatible registry. To publish your project to an
npm-compatible registry, please use npm-publish-git-tag.
As noted earlier
semantic-release-github uses conventional-recommended-bump to determine if a release is needed, and whether that should be a
The process involves
semantic-release-github passing the list of all unreleased commits, along with your project's commit message convention, to
conventional-recommended-bump will either report that no new release is recommended, or it will recommend a new
conventional-recommended-bump indicates that no new release should be made,
semantic-release-github will not release a new version of your project.
If a release is recommended, and no previous version exists, we will always set the first version to
You can employ many different release strategies using an automated tool such as
Below we document a few release strategies. Please don't consider this list exhaustive. There are likely many other ways to decide when it's best to generate a new release for your project.
On Every Push To A Repository With New Commits
Publishing a new release on every push to a repository with new commits is the approach taken by this project. If you take this approach, you can push a single commit, leading to a release for that one change, or you can create multiple commits and push them all at once, leading to a single release containing all those changes.
An example our setup for GitHub CI can be seen in the Continuous Integration and Delivery (CID) Setup section above.
On A Schedule
You may also release your changes on a schedule. For example, using a CI platform like Jenkins CI, you can create and configure a job to run on a given schedule, such as once every two weeks, and, as part of a Post Build Action, run the release tool.
Other CI platforms besides Jenkins also allow you to run a particular action on a given schedule, allowing you to schedule releases as you could with Jenkins CI.
With this strategy all commits that have accumulated in your repository since the last scheduled job run will be incorporated into a single new release. Because this release tool uses
conventional-recommended-bump, which recommends an appropriate new version based on all commits targeted for release, you can be assured that each scheduled release will use a version appropriate for the changes accumulated in that release.
A collection of common issues encountered while using
GitHubError: 404 Project Not Found (404)
In some instances you may see the following error after running
semantic-release-github failed for the following reason - GitHubError: 404 Project Not Found (404)
That error can be caused by one of several reasons.
First, the project, or at least the project URL used by
semantic-release-github, is not valid. Please make sure the repository field in your
package.json is correct. If it is correct, please consider running
semantic-release-github in debug mode to see what URL is being used to interact with GitHub.
Second, you have not set the required environment variable, or the access token assigned to that environment variable does not have access to your project's repository.
To assist users of
semantic-release-github with debugging the behavior of this module we use the debug utility package to print information about the release process to the console. To enable debug message printing, the environment variable
DEBUG, which is the variable used by the
debug package, must be set to a value configured by the package containing the debug messages to be printed.
To print debug messages on a unix system set the environment variable
DEBUG with the name of this package prior to executing
On the Windows command line you may do:
set DEBUG=semantic-release-github semantic-release-github
Node Support Policy
We only support Long-Term Support versions of Node.
We specifically limit our support to LTS versions of Node, not because this package won't work on other versions, but because we have a limited amount of time, and supporting LTS offers the greatest return on that investment.
It's possible this package will work correctly on newer versions of Node. It may even be possible to use this package on older versions of Node, though that's more unlikely as we'll make every effort to take advantage of features available in the oldest LTS version we support.
As each Node LTS version reaches its end-of-life we will remove that version from the
engines property of our package's
package.json file. Removing a Node version is considered a breaking change and will entail the publishing of a new major version of this package. We will not accept any requests to support an end-of-life version of Node. Any merge requests or issues supporting an end-of-life version of Node will be closed.
We will accept code that allows this package to run on newer, non-LTS, versions of Node. Furthermore, we will attempt to ensure our own changes work on the latest version of Node. To help in that commitment, our continuous integration setup runs against all LTS versions of Node in addition the most recent Node release; called current.
engines property. If you encounter issues installing this package, please report the issue to your package manager.
Please read our contributing guide to see how you may contribute to this project.