Github Docker Registry
Learn how to push Docker images as Github packages
GitHub Packages is an artifact storage solution that among other formats, can also be used as a Docker registry. Since the API follows the standard Registry protocol, you can connect the GitHub Docker Registry as a Docker registry in Codefresh and push images from your Codefresh pipelines
GitHub registry naming restrictions
Notice that unlike other Docker registries that you might be familiar with, GitHub Docker images have specific naming restrictions. This happens because all Docker images are placed under a specific Git repository (instead of being placed in a generic Docker registry for your whole GitHub account).
Docker images pushed as GitHub packages
- Are available at the domain
- Must have as first prefix your GitHub username
- Must have as second prefix an existing Git Repository in your GitHub account.
Therefore if you already have a Git repository called
super-git-project under your
joe account, some examples of valid Docker names are:
docker.pkg.github.com/joe/super-git-project/my-docker-image:1.0 docker.pkg.github.com/joe/super-git-project/my-second-docker-image:latest docker.pkg.github.com/joe/super-git-project/my-third-docker-image:34ae34f
If you don’t follow this naming pattern, your push will be rejected.
Creating a personal token
The username to the registry is the same as your GitHub username. For the password you need to create a GitHub personal token.
You need to select at least the following scopes:
repo(if your repository is private)
Once you create the token, note it down.
You can make sure that your token is valid by using it as password on your local workstation with the docker command:
docker login docker.pkg.github.com --username kostis-codefresh [Paste your GitHub token on this prompt] docker tag go-sample-app docker.pkg.github.com/kostis-codefresh/trivial-go-web/go-sample-app:1.0 docker push docker.pkg.github.com/kostis-codefresh/trivial-go-web/go-sample-app:1.0 [...image layers are pushed here...]
And then you will see the Docker image in the packages section of your repository.
Now that you have verified your token we can connect the registry to Codefresh
Connecting the GitHub registry to Codefresh
Go the Registry integration screen at https://g.codefresh.io/account-admin/account-conf/integration/registryNew and add a new Registry by choosing other Registries from the drop-down menu.
Enter your details:
- Registry Name - a unique name for this configuration (arbitrary name)
- Username - your GitHub username.
- Password - your GitHub personal token
- Domain -
- Repository Prefix - your GitHub username (after expanding the Advanced Options sections)
Click the Test Connection button and apply your changes if you get a success message.
Pushing a Docker image as a GitHub package
With the registry integration in place, you can now push a Docker image in any Codefresh pipeline, simply by mentioning the registry by name (
github-packages in my example).
Here is the definition of the Codefresh pipeline.
registry: github-packagesproperty in the
- The fact that we push multiple Docker tags in a single step
- The prefix
image_name: trivial-go-web/my-go-appso that the final image is compliant with GitHub naming.
After the pipeline has finished the Docker tags can also be seen in the GitHub package section of the repository.
You can now treat this registry like any other Codefresh registry.