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

  1. Are available at the domain
  2. Must have as first prefix your GitHub username
  3. 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:

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:

  • write:packages
  • read:packages
  • delete:packages
  • 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 --username kostis-codefresh 
[Paste your GitHub token on this prompt]
docker tag go-sample-app
docker push
[...image layers are pushed here...]

And then you will see the Docker image in the packages section of your repository.

Pushing a Docker image manually to GitHub packages

Pushing a Docker image manually to GitHub packages

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 and add a new Registry by choosing other Registries from the drop-down menu.

Entering GitHub Registry details

Entering GitHub Registry details

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

Codefresh pipeline for GitHub packages

Codefresh pipeline for GitHub packages

Here is the definition of the Codefresh pipeline.


version: '1.0'
- 'my build phase'
- 'my push phase'
    title: Cloning main repository...
    stage: prepare
    type: git-clone
      repo: kostis-codefresh/trivial-go-web
      revision: master
      git: github
    title: Building Docker Image
    stage: 'my build phase'
    type: build
    working_directory: ${{clone}}
      image_name: my-app-image
      dockerfile: Dockerfile
    stage: 'my push phase'
    type: push
    title: Pushing to a registry
    candidate: ${{MyAppDockerImage}}
    - latest
    - 2.0.0
    registry: github-packages
    image_name: trivial-go-web/my-go-app


  • The registry: github-packages property in the pushToMyRegistry step
  • The fact that we push multiple Docker tags in a single step
  • The prefix image_name: trivial-go-web/my-go-app so 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.

Pushing different Docker tags

Pushing different Docker tags

You can now treat this registry like any other Codefresh registry.