Option 1: Linking a GitHub repository


To get your container running on Grand Challenge, you may want to link a GitHub repository to your Algorithm page. When a repository is linked to an algorithm, a new container image will be built automatically each time the repository is tagged. The following requirements need to be met for this workflow to properly work:

  • There needs to be a Dockerfile in the repository's root. This Dockerfile will be used to build the image.
  • The repository needs to have an open-source license. To ensure your license is valid, you can check if the license is listed in your repository's 'about' section:
  • The Grand Challenge GitHub app needs to be installed in the repository

The following licences are currently recognised by Grand Challenge: Apache Licence 2.0, MIT Licence, GNU GPLv3, GNU AGPLv3, Mozilla Public Licence 2.0, Boost Software Licence 1.0, The Unlicence. If your open-source licence is not listed here, please contact us at support@grand-challenge.org.


Install Grand Challenge GitHub app

To install the Grand Challenge GitHub app, navigate to the Containers menu item on your algorithm's page and click the Link GitHub Repo button:

You will be shown a dropdown menu with repositories that already have the app installed. The dropdown will initially be empty. Click link a new GitHub repo here to link a new repository:

You will now be redirected to GitHub.

Complete the steps to install the app for the proper repository. You must have admin rights to the repository so that you can give permission for Grand Challenge to install an app there.

1. Select your GitHub account

2. Select the GitHub repository you want to link to your algorithm

If you see a request badge, please see Link a GitHub repository without admin access. Click Install and Authorize after making your selection. You will now be redirected back to Grand Challenge, where you can select your repository in the dropdown menu. Click Save to link the repository to your algorithm.

The Containers menu item will now display the linked repository.


Build Docker Container

You can now start a new build for your algorithm by tagging your linked GitHub repository. A build will be started for each tag. Note that it could take a little while for the build to start as a worker needs to be available to start the build. The builds for your algorithm will be listed in the Containers menu item. You can view the build logs for each build by clicking the entry in the overview.


Tagging your repository

You can tag your repository using the command line interface, GitHub Desktop, your favorite git program, or the web interface of GitHub. To tag your repository using the web interface of GitHub, create a new release.

To create a new release, navigate to the repository's releases (at github.com/[your username]/[your repository name]/releases) and click Draft a new release:

Enter a name for your release to create the release and automatically tag your repository:

Click Publish release.


Build process

After the repository is tagged, a Docker container will be created automatically using AWS CodeBuild. You can see the progress of this build in the Containers menu item.

The build logs can be viewed by clicking the i button.


Recurse Submodules

If your repository contains submodules that need to be cloned for the Docker build, enable Recurse submodules in the algorithm settings:

1. Update the algorithm settings

2. Enable Recurse submodules

Click Save to store the change.


In case you want to link a GitHub repository you do not have admin access to, the workflow is a little different. This situation can arise, for example, if your repository is managed by your organisation instead of your personal GitHub account. You can recognise this situation from the request badge.

In this case, ask the GitHub admin to install the Grand Challenge app for you. Your organization's GitHub admin can manually install the Grand Challenge app by navigating to github.com/apps/grand-challenge/installations/new and selecting the required repositories. This selection is similar to 2. Select the GitHub repository you want to link to your algorithm above. However, this does not automatically link the repository to your algorithm. After the app is installed, you can manually link the repository to your algorithm by updating the Repo name in your algorithm settings. Write [your organisation name]/[your repository name] here:

Please note that a repository can only be linked to a single algorithm.


Uninstall Grand Challenge GitHub app

To uninstall the GitHub app, navigate to github.com/settings/installations. Under Installed GitHub Apps click on Configure next to Grand Challenge.

Scroll to the bottom and click Uninstall.

Previous section
Next section