release-train

release-train

Contributions welcome.

release-train creates releases for every PR merge in your repository. No magic commit message is required. You only need to label your PRs with the appropriate labels and run release-train (either from the command line or a GitHub Action).

Release-train is inspired by semantic-release and has a few advantages for somebody with my biases:

• It doesn't require special commit messages, so you won't need to squash commits or ask contributors to rebase before merging.
• No need for npm or other package managers.
• No plugin configuration. Release-train has no plugins. You can do anything a plugin would do from the pre-release hook.

Release steps

When run from a release branch, release-train follows these steps to publish a release. Some options such as --check-pr will modify this behavior.

1. Find the previous release tag by searching backward through git history for the first tag formatted like <prefix><semantic version>. When no previous tag is found it uses v0.0.0 or the value from --initial-tag.
2. Find the next release version by looking at the diff between HEAD and the previous release tag and inspecting the pull request where each commit was introduced. The previous version is incremented by the highest change level found.
3. Run pre-release-hook. This is where you can do things like validate the release, built release artifacts or generate a changelog.
4. Create and push the new git tag if --create-tag is set.
5. Create a draft release if --create-release is set. It starts as a draft to avoid publishing a release that doesn't have all the necessary artifacts yet.
6. Upload release assets. Any files written to $ASSETS_DIR will be uploaded as release assets.
7. Publish the release.
8. Emit output including release version, tag, change level, etc that you use in notifications or other actions.

GitHub Action Configuration

Inputs

repo

default: ${{ github.repository }}

GitHub repository in the form of owner/repo.

check-pr

default: ${{ github.event.number }}

Operates as if the given PR has already been merged. Useful for making sure the PR is properly labeled. Skips tag and release.

labels

PR label alias in the form of "=" where is a canonical label.

Accepts multiple values. One value per line.

checkout-dir

default: ${{ github.workspace }}

The directory where the repository is checked out.

ref

default: HEAD

git ref.

github-token

default: ${{ github.token }}

The GitHub token to use for authentication. Must have contents: write permission if creating a release or tag.

create-tag

Whether to create a tag for the release.

Only literal 'true' will be treated as true.

create-release

Whether to create a release. Implies create-tag.

Only literal 'true' will be treated as true.

draft

Leave the release as a draft.

Only literal 'true' will be treated as true.

tag-prefix

default: v

The prefix to use for the tag.

v0

Assert that current major version is 0 and treat breaking changes as minor changes. Errors if the major version is not 0.

Only literal 'true' will be treated as true.

initial-release-tag

default: v0.0.0

The tag to use if no previous version can be found. Set to "" to cause an error instead.

pre-release-hook

Command to run before creating the release. You may abort the release by exiting with a non-zero exit code.

Exit code 0 will continue the release. Exit code 10 will skip the release without error. Any other exit code will abort the release with an error.

You may provide custom release notes by writing to the file at $RELEASE_NOTES_FILE:

echo "my release notes" > "$RELEASE_NOTES_FILE"

You can update the git ref to be released by writing it to the file at $RELEASE_TARGET:

# ... update some files ...
git commit -am "prepare release $RELEASE_TAG"
echo "$(git rev-parse HEAD)" > "$RELEASE_TARGET"

If you create a tag named $RELEASE_TAG, it will be used as the release target instead of either HEAD or the value written to $RELEASE_TARGET.

Any files written to $ASSETS_DIR will be uploaded as release assets.

The environment variables RELEASE_VERSION, RELEASE_TAG, PREVIOUS_VERSION, FIRST_RELEASE, GITHUB_TOKEN, RELEASE_NOTES_FILE, RELEASE_TARGET and ASSETS_DIR will be set.

release-refs

Only allow tags and releases to be created from matching refs. Refs can be patterns accepted by git-show-ref. If undefined, any branch can be used.

Accepts multiple values. One value per line.

tempdir

The prefix to use with mktemp to create a temporary directory.

debug

Enable debug logging.

Only literal 'true' will be treated as true.

release-train-bin

Path to release-train binary. Only needed if you're using a custom release-train binary.

Outputs

previous-ref

A git ref pointing to the previous release, or the current ref if no previous release can be found.

previous-version

The previous version on the release branch.

first-release

Whether this is the first release on the release branch. Either "true" or "false".

release-version

The version of the new release. Empty if no release is called for.

release-tag

The tag of the new release. Empty if no release is called for.

change-level

The level of change in the release. Either "major", "minor", "patch" or "none".

created-tag

Whether a tag was created. Either "true" or "false".

created-release

Whether a release was created. Either "true" or "false".

pre-release-hook-output

The stdout of the pre_release_hook. Empty if pre_release_hook is not set or if the hook returned an exit other than 0 or 10.

pre-release-hook-aborted

Whether pre_release_hook issued an abort by exiting 10. Either "true" or "false".

Command Line Usage

Usage: release-train

Release every PR merge. No magic commit message required.

Flags:
  -h, --help                          Show context-sensitive help.
      --version
      --repo=STRING                   GitHub repository in the form of owner/repo.
      --check-pr=INT                  Operates as if the given PR has already been merged. Useful
                                      for making sure the PR is properly labeled. Skips tag and
                                      release.
      --label=<alias>=<label>;...     PR label alias in the form of "<alias>=<label>" where <label>
                                      is a canonical label.
  -C, --checkout-dir="."              The directory where the repository is checked out.
      --ref="HEAD"                    git ref.
      --create-tag                    Whether to create a tag for the release.
      --create-release                Whether to create a release. Implies create-tag.
      --draft                         Leave the release as a draft.
      --tag-prefix="v"                The prefix to use for the tag.
      --v0                            Assert that current major version is 0 and treat breaking
                                      changes as minor changes. Errors if the major version is not
                                      0.
      --initial-tag="v0.0.0"          The tag to use if no previous version can be found. Set to ""
                                      to cause an error instead.
      --pre-release-hook=<command>    Command to run before creating the release. You may abort the
                                      release by exiting with a non-zero exit code.

                                      Exit code 0 will continue the release. Exit code 10 will skip
                                      the release without error. Any other exit code will abort the
                                      release with an error.

                                      You may provide custom release notes by writing to the file at
                                      $RELEASE_NOTES_FILE:

                                        echo "my release notes" > "$RELEASE_NOTES_FILE"

                                      You can update the git ref to be released by writing it to the
                                      file at $RELEASE_TARGET:

                                        # ... update some files ...
                                        git commit -am "prepare release $RELEASE_TAG"
                                        echo "$(git rev-parse HEAD)" > "$RELEASE_TARGET"

                                      If you create a tag named $RELEASE_TAG, it will be used as the
                                      release target instead of either HEAD or the value written to
                                      $RELEASE_TARGET.

                                      Any files written to $ASSETS_DIR will be uploaded as release
                                      assets.

                                      The environment variables RELEASE_VERSION, RELEASE_TAG,
                                      PREVIOUS_VERSION, FIRST_RELEASE, GITHUB_TOKEN,
                                      RELEASE_NOTES_FILE, RELEASE_TARGET and ASSETS_DIR will be set.
      --release-ref=<branch>,...      Only allow tags and releases to be created from matching refs.
                                      Refs can be patterns accepted by git-show-ref. If undefined,
                                      any branch can be used.
      --push-remote="origin"          The remote to push tags to.
      --tempdir=STRING                The prefix to use with mktemp to create a temporary directory.
      --github-api-url="https://api.github.com"
                                      GitHub API URL.
      --output-format="json"          Output either json our GitHub action output.
      --debug                         Enable debug logging.