Probot: Release

a GitHub App built with probot that publishes build artifacts to various third party services.

Table of Contents

• Target Configuration
  • GitHub
  • NPM
  • Python Package Index
  • Cocoapods
  • Homebrew
  • Cargo
• Store Configuration
  • Amazon S3
  • Zeus CI
• Setup
  • Github App
  • Development
  • Testing
• Deployment

Configuration

The bot will only be active in repositories that contain .github/release.yml. In these repositories it will listen for tags and start a release if all status checks associated to the tag's commit are successful. In case a commit has no status checks, the release is skipped.

This file specifies release targets, stores and more:

Option	Description
store	optional. The store for release artifacts (see below).
targets	optional. List of release targets (see below).
ignoredChecks	optional. A list of ignored status checks. Can be prefixes or entire names.

Target Configuration

The configuration specifies which release targets to run for the repository. To run more targets, list the target identifiers under the target key. If the target key is empty, the bot defaults to the "github" target:

targets:
  - name: github

GitHub (github)

Create a release on Github. If a Markdown changelog is present in the repository, this target tries to read the release name and description from the changelog. Otherwise, defaults to the tag name and tag's commit message.

Environment

none

Configuration

Option	Description
changelog	optional. Path to the changelog file. Defaults to CHANGELOG.md

Example:

targets:
  - name: github
    changelog: CHANGES

NPM (npm)

Releases a NPM package to the public registry. This requires a package tarball generated by npm pack in the release assets. The file will be uploaded to the registry with npm publish. This requires NPM to be authenticated with sufficient permissions to publish the package.

Environment

The npm utility must be installed on the system.

Name	Description
NPM_BIN	optional. Path to the npm executable. Defaults to npm

Configuration

Option	Description
access	optional. Visibility for scoped packages. Defaults to private

Example

targets:
  - name: npm
    access: private

Python Package Index (pypi)

Uploads source dists and wheels to the Python Package Index with twine. The source code bundle or wheels must be in the release assets.

Environment

The twine package must be installed on the system.

Name	Description
TWINE_USERNAME	User name for PyPI with access rights for the package
TWINE_PASSWORD	Password for the PyPI user
TWINE_BIN	optional. Path to twine. Defaults to twine

Configuration

none

Example

targets:
  - pypi

Cocoapods (pods)

Pushes a new podspec to the central cocoapods repository. The Podspec is fetched from the Github repository with the tag that is being released. No release assets are required for this target.

Environment

The cocoapods gem must be installed on the system.

Name	Description
COCOAPODS_TRUNK_TOKEN	The access token to the cocoapods account
COCOAPODS_BIN	optional. Path to cocoapods.

Configuration

Option	Description
spec	Path to the Podspec file in the repository

Example

targets:
  - name: pods
    spec: MyProject.podspec

Homebrew (brew)

Pushes a new or updated homebrew formula to a brew tap repository. The formula is committed directly to the master branch of the tap on GitHub, therefore the bot needs rights to commit to master on that repository. Therefore, formulas on homebrew/core are not supported, yet.

The tap is configured with the mandatory tap parameter in the same format as the brew utility. A tap <org>/<name> will expand to the GitHub repository github.com:<org>/homebrew-<name>.

The formula contents are given as configuration value and can be interpolated with ${ variable }. The interpolation context contains the following variables:

• ref: The tag's reference name. Usually the version number
• sha: The tag's commit SHA
• checksums: A map containing sha256 checksums for every release asset. Use the full filename to access the sha, e.g. checksums['MyProgram.exe']

Environment

none

Configuration

Option	Description
tap	The name of the homebrew tap used to access the GitHub repo
template	The template for contents of the formula file (ruby code)
formula	optional. Name of the formula. Defaults to the repository name
path	optional. Path to store the formula in. Defaults to Formula

Example

targets:
  - name: brew
    tap: octocat/tools     # Expands to github.com:octocat/homebrew-tools
    formula: myproject     # Creates the file myproject.rb
    path: HomebrewFormula  # Creates the file in HomebrewFormula/
    template: >
      class MyProject < Formula
        desc "This is a test for homebrew formulae"
        homepage "https://github.com/octocat/my-project"
        url "https://github.com/octocat/my-project/releases/download/${ref}/binary-darwin"
        version "${ref}"
        sha256 "${checksums['binary-darwin']}"

        def install
          mv "binary-darwin", "myproject"
          bin.install "myproject"
        end
      end

Cargo (cargo)

Publishes a single package or entire workspace on the public crate registry (crates.io). If the workspace contains multiple crates, they are published in an order depending on their dependencies.

Environment

Rustup must be installed and configured on the system.

Name	Description
CARGO_REGISTRY_TOKEN	The access token to the crates.io account
CARGO_BIN	optional. Path to cargo. Defaults to cargo.
CARGO_HOME	optional. Path to the cargo installation.
RUSTUP_HOME	optional. Path to the rustup (toolchains) installation.

Configuration

none

Example

targets:
  - cargo

Store Configuration

The app downloads release artifacts from a configured store provider. After building release assets on a CI server, they need to be uploaded to this store. The default store is Amazon S3 and can be changed via the store parameter in the cofiguration file:

store: s3

Amazon S3 (s3)

Download artifacts from an Amazon S3 bucket. To create a bucket, please refer to the official instructions. Inside this bucket, the bot will always look for a folder with the schema <organization>/<repository>/<commit-sha>.

Environment

Name	Description
S3_BUCKET	The name of the S3 bucket to download files from
S3_ACCESS_KEY	The public access key for the bucket
S3_SECRET_KEY	The secret access key for the bucket

Configuration

store: s3

Zeus CI (zeus)

Download artifacts from Zeus. This requires an API token for a user with access to all repositories. Also, each repository must be activated and a hook configured in the repository settings.

To upload releases, use the zeus-ci command line utility.

Environment

Name	Description
ZEUS_API_TOKEN	API token to authorize with Zeus CI
ZEUS_SERVER_URL	optional. The URL to reach Zeus. Defaults to https://zeus.ci

Configuration

store: zeus

Setup

This Probot app requires authentication tokens and credentials for third party apps in environment variables. Depending on the release targets you wish to use in your installation, you may omit some of the environment variables below.

The project contains a template for environment variables located at .env.example. Copy this file to .env in the project root and adjust all environment variables.

Github App

First, create a GitHub App by following the instructions here. Then, make sure to download the private key and place it in the root directory of this application or set it via the PRIVATE_KEY environment variable. Finally, set the following environment variables:

Name	Description
APP_ID	Unique ID of the GitHub App
WEBHOOK_SECRET	Random webhook secret configured during app creation

Development

To start the development server, make sure the following environment variables are set:

Name	Description
DRY_RUN	Disables actual releases. Set to true
RELEASE_TIMEOUT	Timeout before a release starts. Defaults to 60
SUBDOMAIN	Subdomain for localtunnel to receive webhooks
LOG_LEVEL	Sets the loggers output verbosity. Set to debug

Then, install dependencies and run the bot with:

# Install dependencies
yarn

# Run the bot
yarn start

# Run test watchers
yarn test:watch

We highly recommend to use VSCode and install the recommended extensions. They will configure your IDE to match the coding style, invoke auto formatters every time you save and run tests in the background for you. No need to run the watchers manually.

Testing

The bot includes an automated test suite that includes unit tests, linting and formating checks. Additionally, this command generates a coverage report in coverage/. You can run it with npm:

yarn test

We use prettier for auto-formatting and eslint as linter. Both tools can automatically fix most issues for you. To invoke them, simply run:

yarn fix

Deployment

If you would like to run your own instance of this app, see the docs for deployment.

This app requires these Permissions for the GitHub App:

• Commit statuses: Read-only
• Repository contents: Read & write

Also, the following Events need to be subscribed:

• Status: Commit status updated from the API
• Create: Branch or tag created
• Delete: Branch or tag deleted

Also, make sure all required environment variables are present in the production environment.