Beaker Image Builder

The Beaker Image Builder is a GitHub Action that builds Beaker images automatically in the cloud.

Building images on your own machine can be frustratingly slow, especially over a home internet connection. Faster internet connections in the cloud make image building much faster. With the Beaker Image Builder, the basic workflow is:

Push changes to GitHub.
Wait for the image to build.
Start Beaker experiments with the new image.

Requirements

The Beaker Image Builder can be used with any GitHub repository, private or public.

The repository must have a Dockerfile. If you need help creating a Dockerfile, please contact the Beaker team and we will help you create one. We are working on creating Dockerfile templates for common situations.

Configuration

Beaker User Token

A Beaker user token is required to authenticate with Beaker and create images. The user token is provided to the image builder through a repository secret. To configure it:

Navigate to the main page of the repository.
Click Settings.
In the left sidebar, click Secrets.
Click Add new secret.
Set the name of the secret to BEAKER_TOKEN.
Set the value of the secret to your Beaker user token, which can be found on the Beaker user page.
Click Add secret.

Image Builder Action

To get started, copy the file below into .github/workflows/beaker.yml and commit it.

This example will build a Beaker image for every commit to the master branch. For additional configuration options, see Inputs below.

name: Beaker Image Builder
on:
  push:
    # Run on every commit to the master branch.
    branches: [ master ]
  pull_request:
    # Run on every pull request to the master branch.
    branches: [ master ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    # Check out the repository so that the Beaker Image Builder can access it.
    - uses: actions/checkout@v2
    - name: Beaker Image Builder
      uses: beaker/image-builder@master
      with:
        # Beaker user token. This should be stored as a repository secret using the instructions above.
        beaker_token: ${{ secrets.BEAKER_TOKEN }}

        # Workspace for the built image. If omitted, the default workspace will be used.
        # beaker_workspace: ai2/my-workspace

        # Name for the image. If omitted, the image will named with the repository and commit SHA e.g. repo-abc1234.
        # beaker_image_name: my-custom-image-name-${{ github.SHA }}

        # If set any conflicting image name will be cleared.
        # beaker_image_name_overwrite: "true"

        # Path to the Dockerfile. Defaults to Dockerfile at the root of the repository.
        # dockerfile: directory/Dockerfile

        # Use a Dockerfile template instead of a Dockerfile included in the repository.
        # dockerfile_template: python-pip

        # The GitHub token is used to authenticate with the GitHub Package Registry for caching Docker builds. If omitted, caching will be disabled.
        github_token: ${{ secrets.GITHUB_TOKEN }}

Usage

Once configured, Beaker images will be built for each commit. To check the status of an image build, go to the Actions tab or hover on the status indicator of a commit.

Once an image is created, it will be visible on the Beaker image search page with a link back to the source commit.

Starting an Experiment with the Latest Image

The Beaker image builder creates images with names in the form {GitHub repository}-{Git commit SHA}, e.g. my-repo-4b2891a.

We can do use environment variable substitution in Beaker experiment specs to set the image to the latest version. In your spec, change the image to:

    image: {{ .Env.IMAGE }}

Then start the experiment like this:

IMAGE="my-repo-$(git rev-parse --short HEAD)" beaker experiment create -f spec.yml

This will use the image from the latest commit to start the experiment. Note that you will have to wait for the image to be built before you can start the experiment.

Inputs

`beaker_token`

Required. Beaker user token. This should be stored as a repository secret using the instructions above. The user token grants full access to a Beaker account so it must not be stored in the repository.

`beaker_workspace`

Beaker workspace for the built image. If omitted, the default workspace is used.

`beaker_image_name`

Name for the built image. If omitted, the image will be named using the repository name and the SHA hash of the latest commit, e.g. repo-1234abc.

`beaker_image_name_overwrite`

If set, the image builder will clear the name of any existing image with the desired image name.

`dockerfile`

Path to the Dockerfile. Defaults to Dockerfile at the root of the repository.

`dockerfile_template`

Use a curated Dockerfile provided by Beaker instead of a custom Dockerfile included in the repository. Must be one of the following options:

python-pip: Python 3.7 with GPU support. Dependencies are installed with pip; requirements.txt must exist in the repository.

`github_token`

The GitHub token is used to authenticate with the GitHub Package Registry for caching Docker builds. If omitted, caching will be disabled.

cpkt9762 / image-builder