Getting Started

Before we do anything we must first install auto as a dev dependency.

yarn add -D auto
yarn add -D auto

If you are using auto in a non-javascript project, you can install auto and all it's official plugins via the releases page. Here you will find a build of auto for all major OSes. This build has node bundled so you don't need it installed!

⚠️ If you use yarn@2 none of the default plugins (npm and released) are included so you must install them if you want to use them.

Help

To get detailed help for any command use the --help flag.

auto --help
# or any of auto's command's help
auto shipit --help
auto --help
# or any of auto's command's help
auto shipit --help

Make "Latest Release"

If your project is already published then you need to make sure that your last release is tagged and that it's the Latest Release on GitHub.

To tag your last release find that last commit where you bumped the version and run the following commands with your version number.

git tag v1.2.3
git push --tags
git tag v1.2.3
git push --tags

Then on GitHub go to your project's releases and click Draft a new release. In the Tag version field enter the version number you just tagged and click Publish release.

Now your github project is set up to use auto 🎉

Configuration

Getting started with auto is super easy.

1. Initialize Options (optional)
2. Configure Environment Variables
3. Create Labels
4. Run auto

1. Initialize Options Optional

Initialize the bare minimum options and a few other optional things. This will set you up locally but you will still have to configure environment variables in your CI.

auto init
auto init

2. Configure Environment Variables

You must configure some environment variables for publishing and releasing to work properly.

• GH_TOKEN - Used for publishing the GitHub release and creating labels (create one here) (needs repo permission)

Make sure you give the GH_TOKEN repo permission or shipit will fail!

Local .env Recommended

You can also store these values in a local file at the root of your project named .env. You should make sure to add this file to your .gitignore so you don't commit any keys! These env vars will override these any variable already set on the process. This enables you to have a per project configuration that isn't effected by your global setup.

PROJECT_ROOT/.env:

GH_TOKEN=YOUR_TOKEN
NPM_TOKEN=PUBLISH_TOKEN
GH_TOKEN=YOUR_TOKEN
NPM_TOKEN=PUBLISH_TOKEN

HTTP Proxy

If you are running auto behind a http or https proxy, add either the http_proxy or https_proxy environment variable to your environment. To test locally add it to .env file. Remember this file is only local, so you will need to set the variable in your CI as well.

https_proxy=<PROXYHOST>:<PROXYPORT>
https_proxy=<PROXYHOST>:<PROXYPORT>

3. Create Labels

After that, you need to set up the labels on your GitHub project. The types of labels that auto uses are:

• Versioning Labels - Used to calculate version numbers and make releases. To change them refer to this.
• Changelog Labels - These labels do not effect the version calculation but they will change the section the PR displays in the changelog. These are customizable too, and you can even add your own sections.

To create the labels for your project on GitHub, run the following command with your GH_TOKEN.

GH_TOKEN=YOUR_TOKEN auto create-labels
# or with .env file
auto create-labels
GH_TOKEN=YOUR_TOKEN auto create-labels
# or with .env file
auto create-labels

4. Run auto

auto is written so that each tool it exposes is useful in isolation. You can use as much or as little of auto as you want!

There are two ways you can use auto to create releases.

1. auto shipit - Let auto do everything
2. Sub Commands - Run each command yourself

auto shipit Recommended

To version, changelog, publish and release your code all at the same time you should use the shipit command. shipit runs all commands in the auto workflow and puts it into one meta-command. It's context aware and will make different types of releases based on where you run it.

Read more here.

{
  "scripts": {
    "release": "auto shipit"
  }
}
{
  "scripts": {
    "release": "auto shipit"
  }
}

Do-It-Yourself

All of the functionality of shipit is accessible through all of auto's other commands. Through these commands you can fit parts of auto into your existing release process.

{
  "scripts": {
    "release": "./scripts/release.sh"
  }
}
{
  "scripts": {
    "release": "./scripts/release.sh"
  }
}

Here is an example release script for a npm package:

export PATH=$(npm bin):$PATH

VERSION=`auto version`

## Support for label 'skip-release'
if [ ! -z "$VERSION" ]; then
  ## Update Changelog
  auto changelog

  ## Publish Package
  npm version $VERSION -m "Bump version to: %s [skip ci]"
  npm publish

  ## Create GitHub Release
  git push --follow-tags --set-upstream origin $branch
  auto release
fi
export PATH=$(npm bin):$PATH

VERSION=`auto version`

## Support for label 'skip-release'
if [ ! -z "$VERSION" ]; then
  ## Update Changelog
  auto changelog

  ## Publish Package
  npm version $VERSION -m "Bump version to: %s [skip ci]"
  npm publish

  ## Create GitHub Release
  git push --follow-tags --set-upstream origin $branch
  auto release
fi

Enterprise

If you are using enterprise github auto lets you configure the github API URL that it uses. You can configure this by using the CLI option --github-api, by setting the value in your .autorc, or during auto init.