repo2docker GitHub Action
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 thebinder/
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.
API Reference
See the examples section is very helpful for understanding the inputs and outputs of this Action.
Mandatory Inputs
Exception: if the input parameter NO_PUSH
is set to any value, these values become optional.
DOCKER_USERNAME
: description: Docker registry usernameDOCKER_PASSWORD
: description: Docker registry password
Optional Inputs
NOTEBOOK_USER
: description: username of the primary user in the image. If this is not specified, this is set tojoyvan
. NOTE: This value is also overriden withjovyan
if the parametersBINDER_CACHE
orMYBINDERORG_TAG
are provided.IMAGE_NAME
: name of the image. Example - myusername/myContainer. If not supplied, this defaults to<DOCKER_USERNAME/GITHUB_REPOSITORY_NAME>
.DOCKER_REGISTRY
: description: name of the docker registry. If not supplied, this defaults to DockerHubLATEST_TAG_OFF
: Setting this variable to any value will prevent your image from being tagged withlatest
. 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
: Setting this variable to any value will prevent any images from being pushed to a registry. Furthermore, verbose logging will be enabled in this mode. This is disabled by default.BINDER_CACHE
: Setting this variable to any value will add the filebinder/Dockerfile
that references the docker image that was pushed to the registry by this Action. You cannot use this option if the parameterNO_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 thanDockerfile
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 inbinder/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>
-
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.
Outputs
IMAGE_SHA_NAME
The name of the docker image, which is tagged with the SHA.PUSH_STATUS
: This isfalse
ifNO_PUSH
is provided ortrue
otherwhise.
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/[email protected]
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/[email protected]
with:
NO_PUSH: true
MYBINDERORG_TAG: ${{ github.event.pull_request.head.ref }}
- name: comment on PR with Binder link
uses: actions/[email protected]
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: `[](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 an 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.
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:
- name: Checkout Code
uses: actions/[email protected]
with:
ref: ${{ github.event.pull_request.head.sha }}
- name: update jupyter dependencies with repo2docker
uses: jupyterhub/[email protected]
with:
DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
BINDER_CACHE: true
PUBLIC_REGISTRY_CHECK: true
Push Repo2Docker Image To DockerHub
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/[email protected]
- name: update jupyter dependencies with repo2docker
uses: jupyterhub/[email protected]
with:
DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
Push Image To A Registry Other Than DockerHub
name: Build Notebook Container
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: checkout files in repo
uses: actions/[email protected]
- name: update jupyter dependencies with repo2docker
uses: jupyterhub/[email protected]
with: # make sure username & password matches your registry
DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
DOCKER_REGISTRY: "containers.pkg.github.com"
Change Image Name
When you do not provide an image name your image name defaults to DOCKER_USERNAME/GITHUB_REPOSITORY_NAME
. For example if the user hamelsmu
tried to run this Action from this repo, it would be named hamelsmu/repo2docker-action
. However, sometimes you may want a different image name, you can accomplish by providing the IMAGE_NAME
parameter as illustrated below:
name: Build Notebook Container
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: checkout files in repo
uses: actions/[email protected]
- name: update jupyter dependencies with repo2docker
uses: jupyterhub/[email protected]
with:
DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
IMAGE_NAME: "hamelsmu/my-awesome-image" # this overrides the image name
Test Image Build
You might want to only test the image build withtout pusing to a registry, for example to test a pull request. You can do this by specifying any value for the NO_PUSH
parameter:
name: Build Notebook Container
on: [pull_request]
build-image-without-pushing:
runs-on: ubuntu-latest
steps:
- name: Checkout PR
uses: actions/[email protected]
with:
ref: ${{ github.event.pull_request.head.sha }}
- name: test build
uses: jupyterhub/[email protected]
with:
NO_PUSH: 'true'
IMAGE_NAME: "hamelsmu/repo2docker-test"
When you specify a value for the NO_PUSH
parameter, you can omit the otherwhise mandatory parameters DOCKER_USERNAME
and DOCKER_PASSWORD
.
Contributing To repo2docker-action
See the Contributing Guide.