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.

# 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:

• DOCKER_PASSWORD:

• DOCKER_REGISTRY:

• IMAGE_NAME:

• NOTEBOOK_USER:

• REPO_DIR:

• APPENDIX_FILE:

• LATESTTAGOFF:

• ADDITIONAL_TAG:

• NO_PUSH:

• BINDER_CACHE:

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:

• MYBINDERORG_TAG:

• PUBLICREGISTRYCHECK:

• REPO2DOCKEREXTRAARGS:

• FORCEREPO2DOCKERVERSION:

Outputs

• IMAGESHANAME

• IMAGESHATAG

• PUSH_STATUS:

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=${NBUSER}:${NBUSER} 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

• Any Jupyter Notebook (.ipynb) files inside this directory will

• Optionally, a requirements.txt file inside the image-tests/

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 MYBINDERORGTAG. 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         MYBINDERORGTAG: ${{ github.event.pullrequest.head.ref }}
- name: comment on PR with Binder link       uses: actions/github-script@v1       with:         github-token: ${{secrets.GITHUB_TOKEN}}         script: |           var BRANCHNAME = process.env.BRANCHNAME;           github.issues.createComment({             issue_number: context.issue.number,             owner: context.repo.owner,             repo: context.repo.repo,             body:  :pointleft: Launch a binder notebook on this branch           })       env:         BRANCHNAME: ${{ github.event.pullrequest.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 DOCKERUSERNAME and DOCKERPASSWORD 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 BINDERCACHE to true to enable this option. See the documentation for the parameter BINDERCACHE 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:         DOCKERUSERNAME: ${{ secrets.DOCKERUSERNAME }}         DOCKERPASSWORD: ${{ secrets.DOCKERPASSWORD }}         BINDER_CACHE: true         PUBLICREGISTRYCHECK: 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:         DOCKERUSERNAME: ${{ secrets.DOCKERUSERNAME }}         DOCKERPASSWORD: ${{ secrets.DOCKERPASSWORD }}

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

• Go to your account settings (under your name in the top right), and

• Click 'Create Robot account', give it a memorable name (such as

• In the next screen, select the repository you just created in step (2),

• Once done, click the name of the robot account again. This will give you

• Create these GitHub secrets

• Use the following config for your github action.

name: Build container image
on: [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: # make sure username & password/token matches your registry            DOCKERUSERNAME: ${{ secrets.QUAYUSERNAME }}            DOCKERPASSWORD: ${{ secrets.QUAYPASSWORD }}            DOCKER_REGISTRY: "quay.io"            IMAGE_NAME: "<quay-username>/<repository-name>"

Push Repo2Docker Image To Amazon ECR

• Login to Amazon AWS Console
• Create an individual IAM user who's access key will be used by the GitHub Actions. Make sure the user has permissions to make calls to the Amazon ECR APIs and to push/pull images to the repositories you need.

• Create a new private repository. This will determine the name of your image, and you will push / pull from it. Your image name will be <aws-account-id>.dkr.ecr.<aws-region>.amazonaws.com/<username>/<repository-name>.
• Go to the IAM dashboard, 'Users' section and click on the username created at Step 2.

• Create these GitHub secrets

• Use the following config for your github action.

name: Build container image
on: [push]
jobs:      build:        runs-on: ubuntu-latest        env:          DOCKER_CONFIG: $HOME/.docker        steps:        - name: checkout files in repo          uses: actions/checkout@main
- name: Configure AWS Credentials          uses: aws-actions/configure-aws-credentials@v1          with:            aws-access-key-id: ${{ secrets.AWSACCESSKEY_ID }}            aws-secret-access-key: ${{ secrets.AWSSECRETACCESS_KEY }}            aws-region: <region>
- name: Login to Amazon ECR          id: login-ecr          uses: aws-actions/amazon-ecr-login@v1
- name: Update jupyter dependencies with repo2docker          uses: jupyterhub/repo2docker-action@master          with:            DOCKER_REGISTRY: ${{ steps.login-ecr.outputs.registry }}            IMAGE_NAME: "<aws-username>/<repository-name>"

Push Repo2Docker Image To Google Container Registry

• Login to Google Cloud Console
• Create (or use an existing) Google Cloud Project with the billing activated. This will be the place where the registry hosting the repo2docker image will live.
• Make sure Container Registry API is enabled for this project.
• The repository will be created automatically once the first image is pushed. Your image name will be grc.io/<gcp-project-id>/<repository-name>.
• Create a Service Account to authenticate the calls made by GitHub Actions to our GCP project:

• Click on the service account's name you just created and select the Keys tab. Click on the ADD KEY button, select Create new key, then create a JSON key type. The private key will be saved to your computer. Make sure to store it somewhere secure!
• Create these GitHub secrets

• Use the following config for your github action.

name: Build container image
on: [push]
jobs:      build:        runs-on: ubuntu-latest        env:          DOCKER_CONFIG: $HOME/.docker
steps:        - name: checkout files in repo          uses: actions/checkout@main
- name: Login to GCR          uses: docker/login-action@v1          with:            registry: gcr.io            username: jsonkey            password: ${{ secrets.GCPSAKEY }}
- name: Update jupyter dependencies with repo2docker          uses: jupyterhub/repo2docker-action@master          with:            DOCKER_REGISTRY: gcr.io            IMAGENAME: ${{ secrets.GCPPROJECT_ID }}/<repository-name>

Push Repo2Docker Image To Google Artifact Registry

• Login to Google Cloud Console
• Create (or use an existing) Google Cloud Project with the billing activated. This will be the place where the registry hosting the repo2docker image will live.
• Make sure Artifact Registry API is enabled for this project.
• Create a new artifact repository. This will determine the name and location of your image. Your image name will be <location>-docker.pkg.dev/<gcp-project-id>/<repository-name>
• Create a Service Account to authenticate the calls made by GitHub Actions to our GCP project:

• Click on the service account's name you just created and select the Keys tab. Click on the ADD KEY button, select Create new key, then create a JSON key type. The private key will be saved to your computer. Make sure to store it somewhere secure!
• Create these GitHub secrets

• Use the following config for your github action.

name: Build container image
on: [push]
jobs:      build:        runs-on: ubuntu-latest        env:          DOCKER_CONFIG: $HOME/.docker
steps:        - name: checkout files in repo          uses: actions/checkout@main
- name: Login to GAR          uses: docker/login-action@v1          with:            registry: <location>-docker.pkg.dev            username: jsonkey            password: ${{ secrets.GCPSAKEY }}
- name: Update jupyter dependencies with repo2docker          uses: jupyterhub/repo2docker-action@master          with:            DOCKER_REGISTRY: <location>-docker.pkg.dev            IMAGENAME: ${{ secrets.GCPPROJECT_ID }}/<repository-name>

Push Repo2Docker Image To Azure Container Registry

• Login to Azure Portal
• Create a new container registry. This will determine the name of your image, and you will push / pull from it. Your image name will be <container-registry-name>.azurecr.io/<repository-name>.
• Go to Access Keys option on the left menu.
• Enable Admin user so you can use the registry name as username and admin user access key as password to docker login to your container registry.
• Create these GitHub secrets

• Use the following config for your github action.

name: Build container image
on: [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:            DOCKERUSERNAME: ${{ secrets.ACRUSERNAME }}            DOCKERPASSWORD: ${{ secrets.ACRPASSWORD }}            DOCKER_REGISTRY: <container-registry-name>.azurecr.io            IMAGE_NAME: <repository-name>

Push Repo2Docker Image To GitHub Package Registry

You can push the image to the package registry associated with the GitHub Repository that the repo2docker files are in. No set-up is necessary.

• Use the following config for your github action.

name: Build container image
on: [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: ${{github.actor}}            DOCKERPASSWORD: ${{secrets.GITHUBTOKEN}}            DOCKER_REGISTRY: "ghcr.io"            IMAGE_NAME: "<github-username or orgname>/<repository-name>"

The image url will be ghcr.io/<github-username or orgname>/<repository-name> and appear in "packages" in the right side of the repository window.

Push Repo2Docker Image To Other Registries

If the docker registry accepts a credentials to be passed as a username and password string, you can do it like this.

name: Build Notebook Container
on: [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: # make sure username & password/token matches your registry         DOCKERUSERNAME: ${{ secrets.DOCKERUSERNAME }}         DOCKERPASSWORD: ${{ secrets.DOCKERPASSWORD }}         DOCKER_REGISTRY: "gcr.io"

If the docker registry doesn't credentials to be passed as a username and password strong, or if you want to do it in another way, you can configure credentials to the docker registry ahead of time instead. Below is an incomplete example doing that.

name: Build Notebook Container
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
- name: checkout files in repo       uses: actions/checkout@main
# TODO: add a step here to setup credentials to push to your     #       docker registry before running the repo2docker-action
- name: update jupyter dependencies with repo2docker       uses: jupyterhub/repo2docker-action@master       with:         DOCKER_REGISTRY: your-registry.example.org         IMAGE_NAME: your-image-name

Change Image Name

When you do not provide an image name your image name defaults to DOCKERUSERNAME/GITHUBREPOSITORYNAME. 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/checkout@main
- name: update jupyter dependencies with repo2docker       uses: jupyterhub/repo2docker-action@master       with:         DOCKERUSERNAME: ${{ secrets.DOCKERUSERNAME }}         DOCKERPASSWORD: ${{ secrets.DOCKERPASSWORD }}         IMAGE_NAME: "hamelsmu/my-awesome-image" # this overrides the image name

name: Build Notebook Container
on: [pull_request]
jobs:
  build-image-without-pushing:
    runs-on: ubuntu-latest
    steps:  
    - name: Checkout PR
      uses: actions/checkout@v2
      with:
        ref: ${{ github.event.pull_request.head.sha }}
- name: test build       uses: jupyterhub/repo2docker-action@master       with:         NO_PUSH: 'true'         IMAGE_NAME: "hamelsmu/repo2docker-test"