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:

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

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.

Configuration

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.

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.

Configuration

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

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.

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

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

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:

Development

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

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.