repo2docker GitHub Action

What Can I Do With This Action?
API Reference
Testing the built image
Examples
Contributing

Trigger repo2docker to build a Jupyter enabled Docker image from your GitHub repository and push this image to a Docker registry of your choice. This will automatically attempt to build an environment from configuration files found in your repository in the manner described here.

Read the full docs on repo2docker for more information: https://repo2docker.readthedocs.io

Images generated by this action are automatically tagged with both latest and <SHA> corresponding to the relevant commit SHA on GitHub. Both tags are pushed to the Docker registry specified by the user. If an existing image with the latest tag already exists in your registry, this Action attempts to pull that image as a cache to reduce uncessary build steps.

What Can I Do With This Action?

Use repo2docker to pre-cache images for your own BinderHub cluster, or for mybinder.org.
- You can use this Action to pre-cache Docker images to a Docker registry that you can reference in your repo. For example if you have the file Dockerfile in the binder/ directory relative to the root of your repository with the following contents, this will allow Binder to start quickly by pulling an image you have already built:
```
# This is the image that is built and pushed by this Action (replace this with your image name)
FROM myorg/myimage:latest
...
```
Provide a way to Dockerize data science repositories with Jupyter server enabled that you can deploy to VMs, serverless computing or other services that can serve Docker containers as-a-service.
Maximize reproducibility by allowing authors, without any prior knowledge of Docker, to build and share containers.
Run tests after the image has been built, to make sure package changes don't break your code.

API Reference

See the examples section is very helpful for understanding the inputs and outputs of this Action.

Optional Inputs

DOCKER_USERNAME: description: Docker registry username. If not supplied, credentials must be setup ahead of time.
DOCKER_PASSWORD: description: Docker registry password or access token (recommended). If not supplied, credentials must be setup ahead of time.
DOCKER_REGISTRY: description: domain name of the docker registry. If not supplied, this defaults to DockerHub
IMAGE_NAME: name of the image. Example - myusername/myContainer. If not supplied, this defaults to <DOCKER_USERNAME>/<GITHUB_REPOSITORY_NAME> or <GITHUB_ACTOR>/<GITHUB_REPOSITORY_NAME>.
NOTEBOOK_USER: description: username of the primary user in the image. If this is not specified, this is set to joyvan. NOTE: This value is also overriden with jovyan if the parameters BINDER_CACHE or MYBINDERORG_TAG are provided.
REPO_DIR: Path inside the image where contents of the repositories are copied to, and where all the build operations (such as postBuild) happen. Defaults to /home/<NOTEBOOK_USER> if not set.
APPENDIX_FILE: Path to file containing Dockerfile commands to run at the end of the build. Can be used to customize the resulting image after all standard build steps finish.
LATEST_TAG_OFF: Setting this variable to any value will prevent your image from being tagged with latest. Note that your image is always tagged with the GitHub commit SHA.
ADDITIONAL_TAG: An optional string that specifies the name of an additional tag you would like to apply to the image. Images are already tagged with the relevant GitHub commit SHA.
NO_PUSH: If "true". this variable will prevent any images from being pushed to a registry. Furthermore, verbose logging will be enabled in this mode. Default value is "false".
BINDER_CACHE: Setting this variable to any value will add the file binder/Dockerfile that references the docker image that was pushed to the registry by this Action. You cannot use this option if the parameter NO_PUSH is set. This is disabled by default.
- Note: This Action assumes you are not explicitly using Binder to build your dependencies (You are using this Action to build your dependencies). If a directory binder with other files other than Dockerfile or a directory named .binder/ is detected, this step will be aborted. This Action does not support caching images for Binder where dependencies are defined in binder/Dockerfile (if you are defining your dependencies this way, you probably don't need this Action).
  
  When this parameter is supplied, this Action will add/override binder/Dockerfile in the branch checked out in the Actions runner:
```
### DO NOT EDIT THIS FILE! This Is Automatically Generated And Will Be Overwritten ###
FROM <IMAGE_NAME>
```
COMMIT_MSG: The commit message associated with specifying the BINDER_CACHE flag. If no value is specified, the default commit message of Update image tag will be entered.
MYBINDERORG_TAG: This the Git branch, tag, or commit that you want mybinder.org to proactively build from your repo. This is useful if you wish to reduce startup time on mybinder.org. Your repository must be public for this work, as mybinder.org only works with public repositories.
PUBLIC_REGISTRY_CHECK: Setting this variable to any value will validate that the image pushed to the registry is publicly visible.
REPO2DOCKER_EXTRA_ARGS: Any extra commandline parameters to be passed to the repo2docker build command
FORCE_REPO2DOCKER_VERSION: Force a specific version of repo2docker to be installed. Either in the form of repo2docker==<version> for install from pypi, or git+https://<github-url>@<commit-hash for installing from a github repo / branch

Outputs

IMAGE_SHA_NAME The name of the docker image, which is tagged with the SHA.
IMAGE_SHA_TAG The short tag used as the 'tag' part (after the :) of the docker image name.
PUSH_STATUS: This is false if NO_PUSH is provided or true otherwhise.

Testing the built image

You can automatically test your built image to make sure package additions or removals do not break your code, allowing you to make changes with confidence. pytest is used to run the tests, and pytest-notebook is used to run any Jupyter Notebooks as tests.

This works with any Jupyter kernel. This action will use the Jupyter kernel defined in any notebook you put in image-tests/. This can be used to execute and test notebooks from any language.

Warning

If you are using a Dockerfile to configure your environment, then include COPY --chown=${NB_USER}:${NB_USER} image-tests ${REPO_DIR}/image-tests in your Dockerfile to ensure the correct ownership of this folder within the image.

To use automatic image testing, follow these steps:

Create a directory named image-tests/ in your GitHub repository.
Any .py files you add inside this directory will be discovered and run with pytest inside the built image after the image has successfully built.
Any Jupyter Notebook (.ipynb) files inside this directory will be run with pytest-notebook, and the notebook is considered to have failed if the outputs of the code execution do not match the outputs already in the notebook. A nice diff of the outputs is shown if they differ. See the pytest-notebook docs for more information.
Optionally, a requirements.txt file inside the image-tests/ directory can list additional libraries installed just for the test.

For example, look at the following image environment repository structure:

my-image/
├── environment.yml
└── image-tests
    ├── mytestnotebook.ipynb
    └── mytest.py

This defines three things:

environment.yml is a repo2docker environment file, which defines the packages for the user image
image-tests/mytestnotebook.ipynb is a Jupyter notebook that is already executed so its outputs are included in the ipynb file. When the image is built, this notebook will be re-executed, and the outputs compared against the version stored with the repository.
image-tests/mytest.py is a Python file that will be run with Pytest, and any failures will be reported.

Examples

mybinder.org

A very popular use case for this Action is to cache builds for mybinder.org. If you desire to cache builds for mybinder.org, you must specify the argument MYBINDERORG_TAG. Some examples of doing this are below:

Cache builds on mybinder.org

Proactively build your environment on mybinder.org for any branch. Alternatively, you can use using GitHub Actions to build an image for BindHub generally, including mybinder.org.

name: Binder
on: [push]

jobs:
  Create-MyBinderOrg-Cache:
    runs-on: ubuntu-latest
    steps:
    - name: cache binder build on mybinder.org
      uses: jupyterhub/repo2docker-action@master
      with:
        NO_PUSH: true
        MYBINDERORG_TAG: ${{ github.event.ref }} # This builds the container on mybinder.org with the branch that was pushed on.

Cache Builds On mybinder.org And Provide A Link

Same example as above, but also comment on a PR with a link to the binder environment. Commenting on the PR is optional, and is included here for informational purposes only. In this example the image will only be cached when the pull request is opened but not if the pull request is updated with subsequent commits.

In this example the image will only be cached when the pull request is opened but not if the pull request is updated with subsequent commits.

name: Binder
on:
  pull_request:
    types: [opened, reopened]

jobs:
  Create-Binder-Badge:
    runs-on: ubuntu-latest
    steps:
    - name: cache binder build on mybinder.org
      uses: jupyterhub/repo2docker-action@master
      with:
        NO_PUSH: true
        MYBINDERORG_TAG: ${{ github.event.pull_request.head.ref }}

    - name: comment on PR with Binder link
      uses: actions/github-script@v1
      with:
        github-token: ${{secrets.GITHUB_TOKEN}}
        script: |
          var BRANCH_NAME = process.env.BRANCH_NAME;
          github.issues.createComment({
            issue_number: context.issue.number,
            owner: context.repo.owner,
            repo: context.repo.repo,
            body: `[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/${context.repo.owner}/${context.repo.repo}/${BRANCH_NAME}) :point_left: Launch a binder notebook on this branch`
          })
      env:
        BRANCH_NAME: ${{ github.event.pull_request.head.ref }}

Use GitHub Actions To Cache The Build For BinderHub

Instead of forcing mybinder.org to cache your builds, you can optionally build a Docker image with GitHub Actions and push that to a Docker registry, so that any BinderHub instance, including mybinder.org only has to pull the image. This might give you more control than triggering a build directly on mybinder.org like the method illustrated above. In this example, you must supply the secrets DOCKER_USERNAME and DOCKER_PASSWORD so that Actions can push to DockerHub. Note that, instead of your actual password, you can use an access token — which may be a more secure option.

In this case, we set BINDER_CACHE to true to enable this option. See the documentation for the parameter BINDER_CACHE in the Optional Inputs section for more information.

name: Test
on: push

jobs:
  binder:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout Code
      uses: actions/checkout@v2
      with:
        ref: ${{ github.event.pull_request.head.sha }}

    - name: update jupyter dependencies with repo2docker
      uses: jupyterhub/repo2docker-action@master
      with:
        DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
        DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
        BINDER_CACHE: true
        PUBLIC_REGISTRY_CHECK: true

Push Repo2Docker Image To DockerHub

We recommend creating a personal access token and use that as DOCKER_PASSWORD instead of using your dockerhub password.

name: Build Notebook Container
on: [push] # You may want to trigger this Action on other things than a push.
jobs:
  build:
    runs-on: ubuntu-latest
    steps:

    - name: checkout files in repo
      uses: actions/checkout@main

    - name: update jupyter dependencies with repo2docker
      uses: jupyterhub/repo2docker-action@master
      with:
        DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
        DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}

Push Repo2Docker Image To quay.io

DockerHub now has some pretty strong rate limits, so you might want to push to a different docker repository. quay.io is a popular place, and isn't tied to any particular cloud vendor.

Login to quay.io
Create a new repository. This will determine the name of your image, and you will push / pull from it. Your image name will be quay.io/<username>/<repository-name>.
Go to your account settings (under your name in the top right), and select the 'Robot Accounts' option on the left menu.
Click 'Create Robot account', give it a memorable name (such as <hub-name>_image_builder) and click 'Create'
In the next screen, select the repository you just created in step (2), and give the robot account Write permission to the repository.
Once done, click the name of the robot account again. This will give you its username and password.
Create these GitHub secrets for your repository with the credentials from the robot account:
1. QUAY_USERNAME: user name of the robot account
2. QUAY_PASSWORD: password of the robot account