{"id":13534014,"url":"https://github.com/jupyterhub/repo2docker-action","last_synced_at":"2025-04-06T17:13:04.696Z","repository":{"id":41855634,"uuid":"216683140","full_name":"jupyterhub/repo2docker-action","owner":"jupyterhub","description":"A GitHub action to build data science environment images with repo2docker and push them to registries.","archived":false,"fork":false,"pushed_at":"2024-03-26T20:11:35.000Z","size":285,"stargazers_count":139,"open_issues_count":15,"forks_count":26,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-05-13T07:33:24.379Z","etag":null,"topics":["actions","binder","data-science","datascience","docker","jupyter","jupyter-notebook","repo2docker","repo2docker-action"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jupyterhub.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-21T23:27:05.000Z","updated_at":"2024-05-27T19:51:58.154Z","dependencies_parsed_at":"2023-02-10T17:45:41.169Z","dependency_job_id":"945a8d3c-aa0c-480c-90a7-de8472090071","html_url":"https://github.com/jupyterhub/repo2docker-action","commit_stats":{"total_commits":312,"total_committers":20,"mean_commits":15.6,"dds":"0.27884615384615385","last_synced_commit":"b3cd89ff99f95b00abb5b4db27ec49bb4d3f8c85"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyterhub%2Frepo2docker-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyterhub%2Frepo2docker-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyterhub%2Frepo2docker-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyterhub%2Frepo2docker-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jupyterhub","download_url":"https://codeload.github.com/jupyterhub/repo2docker-action/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247517920,"owners_count":20951719,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","binder","data-science","datascience","docker","jupyter","jupyter-notebook","repo2docker","repo2docker-action"],"created_at":"2024-08-01T07:01:25.404Z","updated_at":"2025-04-06T17:13:04.663Z","avatar_url":"https://github.com/jupyterhub.png","language":"Shell","funding_links":[],"categories":["Community Resources"],"sub_categories":["Machine Learning Ops"],"readme":"![](https://github.com/jupyterhub/repo2docker-action/workflows/Test/badge.svg) [![MLOps](https://img.shields.io/badge/MLOps-black.svg?logo=github\u0026?logoColor=blue)](https://mlops-github.com)\n\n\n# \u003ca href=\"https://github.com/jupyterhub/repo2docker\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/jupyterhub/repo2docker/71eb8058c790a88d223470a55f3ea5b744614dcf/docs/source/_static/images/repo2docker.png\" height=\"40px\" /\u003e\u003c/a\u003e  repo2docker GitHub Action\n\n\n\u003c!-- TOC depthFrom:1 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 --\u003e\n\n- [What Can I Do With This Action?](#what-can-i-do-with-this-action)\n- [API Reference](#api-reference)\n\t- [Mandatory Inputs](#mandatory-inputs)\n\t- [Optional Inputs](#optional-inputs)\n\t- [Outputs](#outputs)\n- [Testing the built image](#testing-the-built-image)\n- [Examples](#examples)\n\t- [mybinder.org](#mybinderorg)\n\t\t- [Cache builds on mybinder.org](#cache-builds-on-mybinderorg)\n\t\t- [Cache Builds On mybinder.org And Provide A Link](#cache-builds-on-mybinderorg-and-provide-a-link)\n\t\t- [Use GitHub Actions To Cache The Build For BinderHub](#use-github-actions-to-cache-the-build-for-binderhub)\n\t- [Push Repo2Docker Image To DockerHub](#push-repo2docker-image-to-dockerhub)\n\t- [Push Repo2Docker Image To quay.io](#push-repo2docker-image-to-quayio)\n\t- [Push Repo2Docker Image To Amazon ECR](#push-repo2docker-image-to-amazon-ecr)\n\t- [Push Repo2Docker Image To Google Container Registry](#push-repo2docker-image-to-google-container-registry)\n\t- [Push Repo2Docker Image To Google Artifact Registry](#push-repo2docker-image-to-google-artifact-registry)\n  \t- [Push Repo2Docker Image To GitHub Package Registry](#push-repo2docker-image-to-github-package-registry)\n\t- [Push Repo2Docker Image To Azure Container Registry](#push-repo2docker-image-to-azure-container-registry)\n\t- [Push Repo2Docker Image To Other Registries](#push-repo2docker-image-to-other-registries)\n\t- [Change Image Name](#change-image-name)\n\t- [Test Image Build](#test-image-build)\n- [Contributing](#contributing-to-repo2docker-action)\n\n\u003c!-- /TOC --\u003e\n\n\nTrigger [repo2docker](https://github.com/jupyter/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](https://repo2docker.readthedocs.io/en/latest/usage.html#where-to-put-configuration-files).\n\nRead the full docs on repo2docker for more information:  https://repo2docker.readthedocs.io\n\nImages generated by this action are automatically tagged with both `latest` and `\u003cSHA\u003e` corresponding to the relevant [commit SHA on GitHub](https://help.github.com/en/github/getting-started-with-github/github-glossary#commit).  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.\n\n# What Can I Do With This Action?\n\n- Use repo2docker to pre-cache images for your own [BinderHub cluster](https://binderhub.readthedocs.io/en/latest/zero-to-binderhub/setup-binderhub.html), or for [mybinder.org](https://mybinder.org/).\n  - 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:\n\n    ```dockerfile\n    # This is the image that is built and pushed by this Action (replace this with your image name)\n    FROM myorg/myimage:latest\n    ...\n    ```\n- Provide a way to Dockerize data science repositories with Jupyter server enabled that you can deploy to VMs, [serverless computing](https://en.wikipedia.org/wiki/Serverless_computing) or other services that can serve Docker containers as-a-service.\n- Maximize reproducibility by allowing authors, without any prior knowledge of Docker, to build and share containers.\n- Run tests after the image has been built, to make sure package changes don't break your code.\n\n# API Reference\n\nSee the [examples](#examples) section is very helpful for understanding the inputs and outputs of this Action.\n\n## Optional Inputs\n\n- **`DOCKER_USERNAME`**:\n    description: Docker registry username.  If not supplied, credentials must be setup ahead of time.\n- **`DOCKER_PASSWORD`**:\n    description: Docker registry password or [access token (recommended)](https://docs.docker.com/docker-hub/access-tokens/).  If not supplied, credentials must be setup ahead of time.\n- **`DOCKER_REGISTRY`**:\n    description: domain name of the docker registry.  If not supplied, this defaults to [DockerHub](https://hub.docker.com/)\n- **`IMAGE_NAME`**:\n    name of the image.  Example - myusername/myContainer.  If not supplied, this defaults to `\u003cDOCKER_USERNAME\u003e/\u003cGITHUB_REPOSITORY_NAME\u003e` or `\u003cGITHUB_ACTOR\u003e/\u003cGITHUB_REPOSITORY_NAME\u003e`.\n- **`NOTEBOOK_USER`**:\n    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.\n- **`REPO_DIR`**:\n    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/\u003cNOTEBOOK_USER\u003e` if not set.\n- **`APPENDIX_FILE`**:\n    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.\n- **`LATEST_TAG_OFF`**:\n    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](https://help.github.com/en/github/getting-started-with-github/github-glossary#commit).  \n- **`ADDITIONAL_TAG`**:\n    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](https://help.github.com/en/github/getting-started-with-github/github-glossary#commit).\n- **`NO_PUSH`**:\n    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\".\n- **`BINDER_CACHE`**:\n    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.\n    - 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).\n\n      When this parameter is supplied, this Action will add/override `binder/Dockerfile` in the branch checked out in the Actions runner:\n      ```dockerfile\n      ### DO NOT EDIT THIS FILE! This Is Automatically Generated And Will Be Overwritten ###\n      FROM \u003cIMAGE_NAME\u003e\n      ```\n- **`COMMIT_MSG`**:\n     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.\n- **`MYBINDERORG_TAG`**:\n    This the Git branch, tag, or commit that you want [mybinder.org](https://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**.\n- **`PUBLIC_REGISTRY_CHECK`**:\n    Setting this variable to any value will validate that the image pushed to the registry is publicly visible.\n- **`REPO2DOCKER_EXTRA_ARGS`**:\n    Any extra commandline parameters to be passed to the repo2docker build command\n- **`FORCE_REPO2DOCKER_VERSION`**:\n    Force a specific version of repo2docker to be installed. Either in the form of `repo2docker==\u003cversion\u003e` for install from pypi, or `git+https://\u003cgithub-url\u003e@\u003ccommit-hash` for installing from a github repo / branch\n\n## Outputs\n\n- **`IMAGE_SHA_NAME`**\n    The name of the docker image, which is tagged with the SHA.\n- **`IMAGE_SHA_TAG`**\n    The short tag used as the 'tag' part (after the `:`) of the docker image name.\n- **`PUSH_STATUS`**:\n    This is `false` if `NO_PUSH` is provided or `true` otherwhise.\n\n# Testing the built image\n\nYou can automatically test your built image to make sure package additions or\nremovals do not break your code, allowing you to make changes with confidence.\n[pytest](https://docs.pytest.org/) is used to run the tests, and\n[pytest-notebook](https://pytest-notebook.readthedocs.io/) is used to\nrun any Jupyter Notebooks as tests.\n\nThis **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.\n\n\u003e [!WARNING]  \n\u003e 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.\n\nTo use automatic image testing, follow these steps:\n\n1. Create a directory named `image-tests/` in your GitHub repository.\n2. Any `.py` files you add inside this directory will be discovered\n   and run with `pytest` inside the built image after the image has\n   successfully built.\n3. Any Jupyter Notebook (`.ipynb`) files inside this directory will\n   be run with [`pytest-notebook`](https://pytest-notebook.readthedocs.io/en/latest/), and the notebook is considered to\n   have *failed* if the outputs of the code execution do not match\n   the outputs already in the notebook. A nice diff of the outputs\n   is shown if they differ. See the [pytest-notebook docs](https://pytest-notebook.readthedocs.io/en/latest/)\n   for more information.\n4. Optionally, a `requirements.txt` file inside the `image-tests/`\n   directory can list additional libraries installed just for the\n   test.\n\nFor example, look at the following image environment repository structure:\n\n```\nmy-image/\n├── environment.yml\n└── image-tests\n    ├── mytestnotebook.ipynb\n    └── mytest.py\n```\n\nThis defines three things:\n\n- **`environment.yml`** is a repo2docker environment file, which defines the packages for the user image\n- **`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.\n- **`image-tests/mytest.py`** is a Python file that will be run with Pytest, and any failures will be reported.\n# Examples\n\n## mybinder.org\n\nA very popular use case for this Action is to cache builds for [mybinder.org](https://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:\n\n### Cache builds on mybinder.org\n\nProactively build your environment on mybinder.org for any branch.  Alternatively, you can use [using GitHub Actions to build an image for BindHub generally](https://github.com/jupyterhub/repo2docker-action#use-github-actions-to-cache-the-build-for-binderhub), including mybinder.org.\n\n```yaml\nname: Binder\non: [push]\n\njobs:\n  Create-MyBinderOrg-Cache:\n    runs-on: ubuntu-latest\n    steps:\n    - name: cache binder build on mybinder.org\n      uses: jupyterhub/repo2docker-action@master\n      with:\n        NO_PUSH: true\n        MYBINDERORG_TAG: ${{ github.event.ref }} # This builds the container on mybinder.org with the branch that was pushed on.\n```\n\n### Cache Builds On mybinder.org And Provide A Link\n\nSame 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.\n\nIn 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.\n\n```yaml\nname: Binder\non:\n  pull_request:\n    types: [opened, reopened]\n\njobs:\n  Create-Binder-Badge:\n    runs-on: ubuntu-latest\n    steps:\n    - name: cache binder build on mybinder.org\n      uses: jupyterhub/repo2docker-action@master\n      with:\n        NO_PUSH: true\n        MYBINDERORG_TAG: ${{ github.event.pull_request.head.ref }}\n\n    - name: comment on PR with Binder link\n      uses: actions/github-script@v1\n      with:\n        github-token: ${{secrets.GITHUB_TOKEN}}\n        script: |\n          var BRANCH_NAME = process.env.BRANCH_NAME;\n          github.issues.createComment({\n            issue_number: context.issue.number,\n            owner: context.repo.owner,\n            repo: context.repo.repo,\n            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`\n          })\n      env:\n        BRANCH_NAME: ${{ github.event.pull_request.head.ref }}\n```        \n\n### Use GitHub Actions To Cache The Build For BinderHub\n\nInstead 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](https://binderhub.readthedocs.io/en/latest/) 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](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-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](https://docs.docker.com/docker-hub/access-tokens/) — which may be a more secure option.\n\nIn this case, we set `BINDER_CACHE` to `true` to enable this option.  See the documentation for the parameter `BINDER_CACHE` in the [Optional Inputs](#optional-inputs) section for more information.\n\n```yaml\nname: Test\non: push\n\njobs:\n  binder:\n    runs-on: ubuntu-latest\n    steps:\n    - name: Checkout Code\n      uses: actions/checkout@v2\n      with:\n        ref: ${{ github.event.pull_request.head.sha }}\n\n    - name: update jupyter dependencies with repo2docker\n      uses: jupyterhub/repo2docker-action@master\n      with:\n        DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}\n        DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}\n        BINDER_CACHE: true\n        PUBLIC_REGISTRY_CHECK: true\n```\n\n## Push Repo2Docker Image To DockerHub\n\nWe recommend creating a [personal access token](https://docs.docker.com/docker-hub/access-tokens/)\nand use that as `DOCKER_PASSWORD` instead of using your dockerhub password.\n\n```yaml\nname: Build Notebook Container\non: [push] # You may want to trigger this Action on other things than a push.\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n\n    - name: checkout files in repo\n      uses: actions/checkout@main\n\n    - name: update jupyter dependencies with repo2docker\n      uses: jupyterhub/repo2docker-action@master\n      with:\n        DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}\n        DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}\n```\n\n## Push Repo2Docker Image To quay.io\n\nDockerHub now has some [pretty strong rate limits](https://docs.docker.com/docker-hub/download-rate-limit/),\nso you might want to push to a different docker repository. \n[quay.io](https://quay.io/) is a popular place, and isn't tied\nto any particular cloud vendor.\n\n1. Login to [quay.io](https://quay.io)\n2. Create a new [repository](https://quay.io/new/). This will determine\n   the name of your image, and you will push / pull from it. Your image\n   name will be `quay.io/\u003cusername\u003e/\u003crepository-name\u003e`.\n3. Go to your account settings (under your name in the top right), and\n   select the 'Robot Accounts' option on the left menu.\n4. Click 'Create Robot account', give it a memorable name (such as\n   `\u003chub-name\u003e_image_builder`) and click 'Create'\n5. In the next screen, select the repository you just created in step (2),\n   and give the robot account `Write` permission to the repository.\n6. Once done, click the name of the robot account again. This will give you\n   its username and password.\n7. Create these [GitHub secrets](https://docs.github.com/en/actions/reference/encrypted-secrets)\n   for your repository with the credentials from the robot account:\n   1. `QUAY_USERNAME`: user name of the robot account\n   2. `QUAY_PASSWORD`: password of the robot account\n   \n8. Use the following config for your github action.\n   ```yaml\n   name: Build container image\n\n   on: [push]\n\n   jobs:\n     build:\n       runs-on: ubuntu-latest\n       steps:\n\n       - name: checkout files in repo\n         uses: actions/checkout@main\n\n       - name: update jupyter dependencies with repo2docker\n         uses: jupyterhub/repo2docker-action@master\n         with: # make sure username \u0026 password/token matches your registry\n           DOCKER_USERNAME: ${{ secrets.QUAY_USERNAME }}\n           DOCKER_PASSWORD: ${{ secrets.QUAY_PASSWORD }}\n           DOCKER_REGISTRY: \"quay.io\"\n           IMAGE_NAME: \"\u003cquay-username\u003e/\u003crepository-name\u003e\"\n\n   ```\n\n## Push Repo2Docker Image To Amazon ECR\n\n1. Login to [Amazon AWS Console](https://console.aws.amazon.com/)\n2. [Create an individual IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#create-iam-users) 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.\nCheckout and follow [Amazon IAM best practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) for the AWS credentials used in GitHub Actions workflows.\n3. Create a new private [repository](https://us-east-2.console.aws.amazon.com/ecr/create-repository). This will determine the name of your image, and you will push / pull from it. Your image name will be `\u003caws-account-id\u003e.dkr.ecr.\u003caws-region\u003e.amazonaws.com/\u003cusername\u003e/\u003crepository-name\u003e`.\n4. Go to the IAM dashboard, ['Users' section](https://console.aws.amazon.com/iamv2/home#/users) and click on the username created at `Step 2`.\nClick on 'Security credentials' tab, right below the 'Summary' section. In the 'Access keys' section, click on the 'Create access key' button. \nOnce done, it will give you an 'Access key ID' and the 'Secret access key'.\n5. Create these [GitHub secrets](https://docs.github.com/en/actions/reference/encrypted-secrets)\n   for your repository with the credentials from the robot account:\n   1. `AWS_ACCESS_KEY_ID`: access key id of the IAM user\n   2. `AWS_SECRET_ACCESS_KEY`: secret access key of the IAM user\n\n6. Use the following config for your github action.\n   ```yaml\n   name: Build container image\n\n   on: [push]\n\n   jobs:\n     build:\n       runs-on: ubuntu-latest\n       env:\n         DOCKER_CONFIG: $HOME/.docker\n       steps:\n       - name: checkout files in repo\n         uses: actions/checkout@main\n\n       - name: Configure AWS Credentials\n         uses: aws-actions/configure-aws-credentials@v1\n         with:\n           aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}\n           aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n           aws-region: \u003cregion\u003e\n\n       - name: Login to Amazon ECR\n         id: login-ecr\n         uses: aws-actions/amazon-ecr-login@v1\n\n\n       - name: Update jupyter dependencies with repo2docker\n         uses: jupyterhub/repo2docker-action@master\n         with:\n           DOCKER_REGISTRY: ${{ steps.login-ecr.outputs.registry }}\n           IMAGE_NAME: \"\u003caws-username\u003e/\u003crepository-name\u003e\"\n\n   ```\n\n## Push Repo2Docker Image To Google Container Registry\n\n1. Login to [Google Cloud Console](https://console.cloud.google.com)\n2. 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.\n3. Make sure [`Container Registry API`](https://console.cloud.google.com/apis/library/containerregistry.googleapis.com) is enabled for this project.\n4. The repository will be created automatically once the first image is pushed. Your image name will be `grc.io/\u003cgcp-project-id\u003e/\u003crepository-name\u003e`.\n5. Create a Service Account to authenticate the calls made by GitHub Actions to our GCP project:\n   - In the Cloud Console, go to the [Service Accounts page](https://console.cloud.google.com/iam-admin/serviceaccounts).\n   - Make sure the right project is selected in the drop-down menu above.\n   - Click on [`Create Service Account`](https://console.cloud.google.com/iam-admin/serviceaccounts/create)\n   - Enter a service account name — give it a memorable name (such as `\u003chub-name\u003e_image_builder`).\n   - Grant this service account access to project. As a best practice, grant it only the minimum permissions: `Cloud Run Admin`, `Service Account User`, and `Storage Admin`.\n6. 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!\n7. Create these [GitHub secrets](https://docs.github.com/en/actions/reference/encrypted-secrets)\n   for your repository with the credentials from the robot account:\n   1. `GCP_SA_KEY`: the private key of the service account created in the previous step\n   2. `GCP_PROJECT_ID`: the id of the Google Cloud Project\n\n8. Use the following config for your github action.\n   ```yaml\n   name: Build container image\n\n   on: [push]\n\n   jobs:\n     build:\n       runs-on: ubuntu-latest\n       env:\n         DOCKER_CONFIG: $HOME/.docker\n\n       steps:\n       - name: checkout files in repo\n         uses: actions/checkout@main\n\n       - name: Login to GCR\n         uses: docker/login-action@v1\n         with:\n           registry: gcr.io\n           username: _json_key\n           password: ${{ secrets.GCP_SA_KEY }}\n\n       - name: Update jupyter dependencies with repo2docker\n         uses: jupyterhub/repo2docker-action@master\n         with:\n           DOCKER_REGISTRY: gcr.io\n           IMAGE_NAME: ${{ secrets.GCP_PROJECT_ID }}/\u003crepository-name\u003e\n     ```\n\n## Push Repo2Docker Image To Google Artifact Registry\n\n1. Login to [Google Cloud Console](https://console.cloud.google.com)\n2. 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.\n3. Make sure [`Artifact Registry API`](https://console.cloud.google.com/apis/library/artifactregistry.googleapis.com) is enabled for this project.\n4. Create a new [artifact repository](https://console.cloud.google.com/artifacts/create-repo). This will determine the name and location of your image. Your image name will be `\u003clocation\u003e-docker.pkg.dev/\u003cgcp-project-id\u003e/\u003crepository-name\u003e`\n5. Create a Service Account to authenticate the calls made by GitHub Actions to our GCP project:\n   - In the Cloud Console, go to the [Service Accounts page](https://console.cloud.google.com/iam-admin/serviceaccounts).\n   - Make sure the right project is selected in the drop-down menu above.\n   - Click on [`Create Service Account`](https://console.cloud.google.com/iam-admin/serviceaccounts/create)\n   - Enter a service account name — give it a memorable name (such as `\u003chub-name\u003e_image_builder`).\n   - Grant this service account access to project. As a best practice, grant it only the minimum permissions: `Cloud Run Admin`, `Service Account User`, `Storage Admin`, `Artifact Registry Repository Administrator`.\n6. 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!\n7. Create these [GitHub secrets](https://docs.github.com/en/actions/reference/encrypted-secrets)\n   for your repository with the credentials from the robot account:\n   1. `GCP_SA_KEY`: the private key of the service account created in the previous step\n   2. `GCP_PROJECT_ID`: the id of the Google Cloud Project\n\n8. Use the following config for your github action.\n   ```yaml\n   name: Build container image\n\n   on: [push]\n\n   jobs:\n     build:\n       runs-on: ubuntu-latest\n       env:\n         DOCKER_CONFIG: $HOME/.docker\n\n       steps:\n       - name: checkout files in repo\n         uses: actions/checkout@main\n\n       - name: Login to GAR\n         uses: docker/login-action@v1\n         with:\n           registry: \u003clocation\u003e-docker.pkg.dev\n           username: _json_key\n           password: ${{ secrets.GCP_SA_KEY }}\n\n       - name: Update jupyter dependencies with repo2docker\n         uses: jupyterhub/repo2docker-action@master\n         with:\n           DOCKER_REGISTRY: \u003clocation\u003e-docker.pkg.dev\n           IMAGE_NAME: ${{ secrets.GCP_PROJECT_ID }}/\u003crepository-name\u003e\n\n     ```\n\n## Push Repo2Docker Image To Azure Container Registry\n\n1. Login to [Azure Portal](https://portal.azure.com/)\n2. Create a new [container registry](https://portal.azure.com/#create/Microsoft.ContainerRegistry). This will determine the name of your image, and you will push / pull from it. Your image name will be `\u003ccontainer-registry-name\u003e.azurecr.io/\u003crepository-name\u003e`.\n3. Go to `Access Keys` option on the left menu.\n4. 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.\n5. Create these [GitHub secrets](https://docs.github.com/en/actions/reference/encrypted-secrets)\n   for your repository with the credentials from the robot account:\n   1. `ACR_USERNAME`: the registry name\n   2. `ACR_PASSWORD`: the access key of the admin user\n\n6. Use the following config for your github action.\n   ```yaml\n   name: Build container image\n\n   on: [push]\n\n   jobs:\n     build:\n       runs-on: ubuntu-latest\n\n       steps:\n       - name: checkout files in repo\n         uses: actions/checkout@main\n\n       - name: Update jupyter dependencies with repo2docker\n         uses: jupyterhub/repo2docker-action@master\n         with:\n           DOCKER_USERNAME: ${{ secrets.ACR_USERNAME }}\n           DOCKER_PASSWORD: ${{ secrets.ACR_PASSWORD }}\n           DOCKER_REGISTRY: \u003ccontainer-registry-name\u003e.azurecr.io\n           IMAGE_NAME: \u003crepository-name\u003e\n\n   ```\n\n## Push Repo2Docker Image To GitHub Package Registry\n\nYou can push the image to the package registry associated with the GitHub Repository that the repo2docker files are in. No set-up is necessary.\n\n1. Use the following config for your github action.\n   ```yaml\n   name: Build container image\n\n   on: [push]\n\n   jobs:\n     build:\n       runs-on: ubuntu-latest\n       steps:\n\n       - name: checkout files in repo\n         uses: actions/checkout@main\n\n       - name: update jupyter dependencies with repo2docker\n         uses: jupyterhub/repo2docker-action@master\n         with: \n           DOCKER_USERNAME: ${{github.actor}}\n           DOCKER_PASSWORD: ${{secrets.GITHUB_TOKEN}}\n           DOCKER_REGISTRY: \"ghcr.io\"\n           IMAGE_NAME: \"\u003cgithub-username or orgname\u003e/\u003crepository-name\u003e\"\n   ```\n\nThe image url will be `ghcr.io/\u003cgithub-username or orgname\u003e/\u003crepository-name\u003e` and appear in \"packages\" in the right side of the repository window.\n\n## Push Repo2Docker Image To Other Registries\n\nIf the docker registry accepts a credentials to be passed as a username and password string, you can do it like this.\n\n```yaml\nname: Build Notebook Container\non: [push]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n\n    - name: checkout files in repo\n      uses: actions/checkout@main\n\n    - name: update jupyter dependencies with repo2docker\n      uses: jupyterhub/repo2docker-action@master\n      with: # make sure username \u0026 password/token matches your registry\n        DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}\n        DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}\n        DOCKER_REGISTRY: \"gcr.io\"\n```\n\nIf 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.\n\n```yaml\nname: Build Notebook Container\non: [push]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n\n    - name: checkout files in repo\n      uses: actions/checkout@main\n\n    # TODO: add a step here to setup credentials to push to your\n    #       docker registry before running the repo2docker-action\n\n    - name: update jupyter dependencies with repo2docker\n      uses: jupyterhub/repo2docker-action@master\n      with:\n        DOCKER_REGISTRY: your-registry.example.org\n        IMAGE_NAME: your-image-name\n```\n\n## Change Image Name\n\nWhen you do not provide an image name your image name defaults to `DOCKER_USERNAME/GITHUB_REPOSITORY_NAME`.  For example if the user [`hamelsmu`](http://www.github.com/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:\n\n```yaml\nname: Build Notebook Container\non: [push]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n\n    - name: checkout files in repo\n      uses: actions/checkout@main\n\n    - name: update jupyter dependencies with repo2docker\n      uses: jupyterhub/repo2docker-action@master\n      with:\n        DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}\n        DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}\n        IMAGE_NAME: \"hamelsmu/my-awesome-image\" # this overrides the image name\n```\n\n## Test Image Build\n\nYou might want to only test the image build withtout pushing to a registry, for example to test a pull request. You can do this by setting the `NO_PUSH` parameter to 'true':\n\n```yaml\nname: Build Notebook Container\non: [pull_request]\njobs:\n  build-image-without-pushing:\n    runs-on: ubuntu-latest\n    steps:  \n    - name: Checkout PR\n      uses: actions/checkout@v2\n      with:\n        ref: ${{ github.event.pull_request.head.sha }}\n\n    - name: test build\n      uses: jupyterhub/repo2docker-action@master\n      with:\n        NO_PUSH: 'true'\n        IMAGE_NAME: \"hamelsmu/repo2docker-test\"\n```\n\n_When you specify a value for the `NO_PUSH` parameter, you can omit the otherwhise mandatory parameters `DOCKER_USERNAME` and `DOCKER_PASSWORD`._\n\n# Contributing To repo2docker-action\n\nSee the [Contributing Guide](./CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjupyterhub%2Frepo2docker-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjupyterhub%2Frepo2docker-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjupyterhub%2Frepo2docker-action/lists"}