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 email@example.com.
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.
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
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:
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
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
Save to store the change.
Link a GitHub repository without admin access¶
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
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