Skip to content
This repository was archived by the owner on Aug 7, 2023. It is now read-only.
This repository was archived by the owner on Aug 7, 2023. It is now read-only.

Look into deployment from CI #18

Open
@Arcanemagus

Description

@Arcanemagus

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/account
  • GITHUB_TOKEN: Follow these instructions to create a new token. When creating it you need to give it public_repo permissions:
    image

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:

image

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions