automatic-release
Advanced tools
Automates the full release process for Open Source projects on GitHub, using Travis CI and deploying to NPM.
Automates the release process for GitHub projects.
Creating and managing projects on GitHub usually requires lots of time and effort. When developing libraries, in particular, the tasks required for publishing new releases are often very long, complex, and error-prone.
Meet automatic-release, a NodeJS-based command line tool which makes new library releases "a matter of a single click", allowing developers to focus on the important things - developing! automatic-release achieves that by automating the whole release process. This includes
Once following the Git Flow branching model and the Angular Git Commit Conventions as well as using a Continuous Integration platform such as Travis CI, publishing a new library release to NPM & GitHub gets as simple as merging the latest
developstate into themasterbranch.
You can get automatic-release via npm by either adding it as a new devDependency to your package.json file and running
npm install, or running the following command:
npm install automatic-release --save-dev
automatic-release requires at least NodeJS 7.6 (or higher). Earlier 7.x versions of NodeJS (7.0 to 7.5) might also work when
executing automatic-release using the --harmony-async-await flag.
automatic-release expects a package.json and a CHANGELOG.md file at the project root. Further on, the package.json file should
at least contain a package name, a version, and a valid GitHub repository URL.
Internally, automatic-release analyzes the commit history in order to evaluate version numbers and generate changelogs. To make this work, developers must follow a specific convention when making commits. Such a commit convention usually describes the structure and naming of the commit message (type, scope, message), the commit body (further details), and the commit footer (breaking changes, issues this commit fixes).
As of now, automatic-release expects the Angular Commit Message Format to be used. For more details, read the full Angular Commit Message Guidelines. In short, commits following this convention look like the following:
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
Quick Tip: I personally do not recommend forcing developers to follow this convention for every single commit, as this might lead to less commits being made in general. Instead, it's probably better to squash commits when merging PRs, and then only name the PR merge commit after the naming convention.
Moreover, following the Git Flow branching model is highly recommended. To summarize, Git Flow proposes a number of branch types such as the master branch (containing the latest release), the develop branch (as the "master during development"), and multiple feature & bugfix branches (enabling developers to work in parallel). For more details, continue reading at A successful Git branching model.
Utilizing this concept simplifies the release management significantly (amongst further advantages it has for the overall development workflow). However, automatic-release does not require all the branches Git Flow proposes to exist. It only expects the following two branches to exist and get used correctly:
Quick Tip: Makde the develop branch the project's default branch so that Pull Requests are always opened against develop and not master.
First of all, setup Travis CI for your GitHub repository by
.travis.yml configuration file set up.For further details on how to setup Travis CI, continue reading the official Travis CI - Getting Started guide.
Within Travis CI, select your GitHub project, go to More Options / Settings and make sure the following Environment Variables are defined:
GH_TOKEN: This environment variable defines the GitHub Access Token, enabling automatic-release to push commits and tags to GitHub
as well as create GitHub releases.
To generate this token, visit your GitHub - Personal Access Tokens page, click Generate new token, select (at least) the repo / public_repo scope access and finish up by hitting Generate token.
NPM_TOKEN: This environment variable defines the NPM Authentication Token, needed by Travis CI to deploy your library to the public
NPM registry.
Getting this token is as simple as logging into your NPM account locally and copying the
authTokenfrom your.npmrcfile. A detailed instruction can be found right here.
FORCE_COLOR: This environment variable (forcefully) enables colorful logging output when set to 1. If the automatic-release logging
output is black'n'white only this variable might help.
Finally, setup the automated release process by extending the .travis.yml configuration file. First, make sure bothh the master and
develop branches are included in the branches block. For example:
branches:
only:
- master
- develop
Next, add automatic-release to the scripts block of your package.json file to make it available to npm run commands:
{
"scripts": {
"automatic-release": "automatic-release"
}
}
Then, define a new Travis CI job for releases containing (at least) the following commands (replace <...> with actual data):
jobs:
include:
- stage: release
before_install:
# Clone the whole repository because we also need the develop branch for releasing
- git clone "https://github.com/$TRAVIS_REPO_SLUG.git" "$TRAVIS_REPO_SLUG";
- cd "$TRAVIS_REPO_SLUG";
- git checkout -qf "$TRAVIS_COMMIT";
# Fix Travis CI issue of detached heads in git
- git checkout master
install:
# ...
script:
# ...
before_deploy:
# Login to Git to be able to make commits (required by automatic-release)
- git config --global user.name "<GITHUB-USER-NAME>"; # REPLACE!
- git config --global user.email "<GITHUB-USER-EMAIL>"; # REPLACE!
- git config credential.helper "store --file=.git/credentials";
- echo "https://$GH_TOKEN:@github.com" > .git/credentials;
# Run automatic-release
- npm run automatic-release
deploy:
provider: npm
email: <NPM_USER_EMAIL> # REPLACE!
api_key: "$NPM_TOKEN"
skip_cleanup: true
If you plan to publish from a directory other than the root, don't forget to navigate into the folder in the
before_deploysection. Also, you might need to copy the updatedpackage.jsonandCHANGELOG.mdfile into your publish directory after running automatic-release yet before running the npm deploy.
Finally, use the release job defined above in your stages with the master branch condition:
stages:
- name: release
if: branch = master
Dominique Müller
FAQs
Automates the full release process for Open Source projects on GitHub, using Travis CI and deploying to NPM.
We found that automatic-release demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Python 3.14 adds template strings, deferred annotations, and subinterpreters, plus free-threaded mode, an experimental JIT, and Sigstore verification.
Security News
Former RubyGems maintainers have launched The Gem Cooperative, a new community-run project aimed at rebuilding open governance in the Ruby ecosystem.
Security News
An opt-in lazy import keyword aims to speed up Python startups, especially CLIs, without the ecosystem-wide risks that sank PEP 690.