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 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.

Recommended Usage

You must copy the contents of your repository to use this action as illustrated below:

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@master

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

Mandatory Inputs

Exception: if the input parameter NO_PUSH is set to any value, these values become optional.

DOCKER_USERNAME: description: Docker registry username
DOCKER_PASSWORD: description: Docker registry password

Optional Inputs

NOTEBOOK_USER: description: username of the primary user in the image. If this is not specified, the username in the default environment variable GITHUB_ACTOR is used.
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 DockerHub
LATEST_TAG_OFF: Setting this variable to any value will prevent your image from being tagged with latest, in additiona to the GitHub commit SHA. This is enabled by default.
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 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/Docker (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_CACHE: Does the same thing as the parameter BINDER_CACHE, except also checks that the docker image is publicly visible, which is required by mybinder.org to pull your image.
PUBLIC_REGISTRY_CHECK: Setting this variable to any value will validate that the image pushed to the registry is publicly visible. This is automatically enabled when the parameter MYBINDERORG_CACHE is set.

Outputs

IMAGE_SHA_NAME The name of the docker image, which is tagged with the SHA.
PUSH_STATUS: This is false if NO_PUSH is provided or true otherwhise.

Examples

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/checkout@master

    - name: update jupyter dependencies with repo2docker
      uses: machine-learning-apps/repo2docker-action@master
      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 don't 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/checkout@master

    - name: update jupyter dependencies with repo2docker
      uses: machine-learning-apps/repo2docker-action@master
      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/checkout@v2
      with:
        ref: ${{ github.event.pull_request.head.sha }}

    - name: test build
      uses: machine-learning-apps/repo2docker-action@master
      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.

manics/repo2docker-action