Look into deployment from CI #18
Description
Automated Deployment
We have a mostly complete setup for getting automated deployment of your package whenever commits are made that should be released out to the users. If you are just interested in how to get this working, see the Setup section. If you are curious about all of the tools that make this possible and how they interact see the Description section. See the Limitations section for current potential blockers for enabling this in your repository, feel free to comment below with any additional questions or clarifications.
Setup
Currently you must have Travis CI configured on the project in order to utilize this setup, this is a limitation of the tool used to verify that the commit messages are following the proper format and is being looked into.
Required Environment Variables
You must have Admin level permissions on a repository in order to complete setup! If you need help with this please contact @Arcanemagus on the Atom Slack team.
The following environment variables are required to be configured in the environment by @semantic-release/apm-config
:
ATOM_ACCESS_TOKEN
: The value to use for this can be found here: https://atom.io/accountGITHUB_TOKEN
: Follow these instructions to create a new token. When creating it you need to give itpublic_repo
permissions:
When you have values ready for these tokens you will need to add them to the environment for your repositories builds. The easiest way to do this is to do so from the web UI settings, for example: https://travis-ci.org/AtomLinter/linter-js-yaml/settings
When there simply add the values in the Environment Variables section, don't worry about the values as they are encrypted and in addition are not visible once added:
Alternatively you can follow these instructions to add the encrypted values directly into the repositories .travis.yml
, like this.
Travis CI Build
The next step that likely needs additional work on your part is to configure the Travis CI build, the initial PR does some of the steps needed, however there are additional changes required to get a working setup.
You'll need to add a jobs
and stages
section in order to properly control the flow of the deployment. It's also likely that you will need to modify the stage that the build-package.sh
script is running at, as the simplest setup is to have it as the install
stage.
As most projects are running on Linux CI builds a good example setup can be found in the linter-js-yaml .travis.yml
file. If you run into any issues getting things working feel free to contact me as above!
Profit?
Ideally the rest of the configuration should have been taken care of by the initial PR, so at this point any time commits are made that should trigger a release it will be taken care of automatically for you.
Description
If you are interested in all of the parts going into this, this is the section for you!
Commit Messages
At the heart of how all this works is the requirement that your commit messages all follow a specified standard, which lets the tools determine whether or not a release should be made, and if so what changes it will include that should be displayed to users.
Under the default configuration your commit messages will now be required to follow the Conventional Commits standard. This standard is quite flexible, with the default syntax being:
<type>[optional scope]: <description>
[optional body]
[optional footer]
The only important <types>
are fix
and feat
, corresponding to a patch
level change and minor
level change respectively. If your commit message includes the words BREAKING CHANGE:
at the start of the body or footer will trigger a major
release of your package. Further details can be found on their website. Any <type>
other than the ones listed above is ignored as far as releases are concerned, so feel free to use whatever you like, you can find some suggested types in the Angular Commit style, as that is what Conventional Commits are based on.
Additional commit message formats are supported, you can find a full list in the commit-analyzer options.
Commit Enforcement
The next important part is making sure that all commit messages actually fit within the chosen style, otherwise there wouldn't be a point to having a style 😆. This is accomplished with the commitlint tool, which allows you to lint your commit messages themselves, ensuring they fit within the style you have chosen. This tool is a standalone tool, and as nobody would remember to run it for every commit themselves, the Husky tool is used to automatically install git
hooks when you run npm install
, with these hooks being configured to run commitlint
on your commit message before it is actually written to the repository. This tool is also configured to run within CI builds, preventing somebody from skipping the hook installation and trying to make a commit message that doesn't follow the required style.
Deployment
The last part is that during your CI builds on commits directly to the master
branch the semantic-release
utility is called that pulls all the commits done since the last release together, determines if any release should be done based on those commits, and what level it should be. It then generates a CHANGELOG entry, commits the changes necessary for the release, pushes it back up to GitHub, tags a release, and publishes it on apm
. Magic! ✨
I'll let them describe the process in more detail over in their README.
Limitations
There are three major limitations to this process.
Commits must follow the standard
Without the commits following the standard the tool has no idea what they are doing and will likely just skip them. The configuration recommended requires all commits to follow the standard, letting it dictate what is included or not. An alternative way of working with this would be to drop this requirement and only do a "release commit" that follows the standard when you want to. That somewhat defeats the purpose of an automated system like this though, essentially delegating it to just running apm publish
for you.
Only Travis CI is supported
This is primarily a limitation of the commitlint
tool, I'm working on a version of the CI runner for this to work in the Circle CI environment, but haven't gotten many of the possible edge cases working yet.
Administrator access required to set it up
Many of the security benefits possible with automated deployments are currently actually required to be bypassed only for administrator accounts under this setup. This is because right now the process needed to do the deployment is done from within the CI builds, so they can't wait for all required CI builds to complete before running. I'll be following semantic-release/semantic-release#585 which is how they plan to work around this by creating their own GitHub app which could run as a separate "CI" process after all the required builds have finished.
Problems?
Again, if you run into any problems getting this running, feel free to contact @Arcanemagus on the Atom Slack team and I will work with you to get things running properly.
Note: The original description follows.
It would be great if we could deploy new versions from CI, allowing people with only write access to repositories with protected branches to still be able to deploy new versions.
There was some initial work towards this over in linter-clang
by @keplersj here. It utilized an experimental deployment engine from travis-ci/dpl#401 discussed further in travis-ci/dpl#378.