Setting up GitHub Package Registry with Docker and Golang

Generally, for any programming language, to run your application you need to create some kind of package (npm for JavaScript, NuGet for C#, ...) and then store it somewhere. In case of Docker, people usually just throw their images into Docker Hub, but we now have new alternative here...

The alternative is GitHub Package Registry - it has been in beta for a while now and it seems that more and more people are getting access to it, so it feels like the time has come to explore its features, here specifically for Docker and Go projects.

This post is part of the series "All You Need For Your Next Golang Project", if that sound interesting, go ahead and checkout previous part here.

Note: This article is applicable to any project using docker images, not just Golang.

Why Use GitHub Registry

First of all, why should you even consider switching from, let's say, Docker Hub or any other registry, to GitHub Package Registry:

If you are already using GitHub as your SCM, then it makes sense to use GitHub Package Registry, as it allows you to keep everything in one place instead of pushing your packages elsewhere.
There is another shiny new (beta) feature of GitHub - Actions, which you can leverage in conjunction with GitHub Package Registry (more on this in another post...).
Even though I consider Docker images superior to e.g. npm packages, you can also push those to the GitHub Package Registry, if you prefer non-Docker artifacts.

Let's Do It!

So, now, let's see how to use it. Let's start with building and tagging your image:

Note: If you are working with Go, then you might want to checkout my repository here, where all the GitHub Package Registry fun is already tied into Makefile targets.


docker build -t  docker.pkg.github.com/<gh-username>/<gh-repo-name>/<image-name>:<version> .

# For Example
docker build -t  docker.pkg.github.com/martinheinz/go-project-blueprint/blueprint:latest .

To be able to push images to GitHub Package Registry, you need to name it using format shown above - which really is just URL of registry with your GitHub username and repository name.

Next, how do we access it?

First, to be able to authenticate ourselves with GitHub Package Registry, we need to create personal access token. This access token must have read:packages and write:packages scope and additionally in case you have a private repository, you will have to include repo scope as well.

There is already very nice guide on GitHub help website on how to create personal token, so I'm not gonna copy and paste the steps here. You can read about it here.

Now, that we have personal token let's login:


docker login docker.pkg.github.com -u <USERNAME> -p <GITHUB_TOKEN>

# For Example:
docker login docker.pkg.github.com -u MartinHeinz -p dgni723a3k67fsdj65e # Not an actual token, so don't even try

Finally, time to push our image:


docker push docker.pkg.github.com/<gh-username>/<gh-repo-name>/<image-name>:<version>

# For Example:
docker push docker.pkg.github.com/martinheinz/go-project-blueprint/blueprint:latest

And obviously you can also pull the image:


docker pull docker.pkg.github.com/<gh-username>/<gh-repo-name>/<image-name>:<version>

# For Example:
docker pull docker.pkg.github.com/martinheinz/go-project-blueprint/blueprint:latest

Use It in Your CI/CD Pipeline

Last thing we might want to to do with GitHub Package Registry is to integrate it with CI/CD tools. Let's look at how it can be done with Travis (Full .travis.yml can be found in my repository here):


# ...
- language: go  # Push if on master
      services:
        - docker
      if: branch = master
      script:
        - export GO111MODULE=on
        - go mod vendor  # Download dependencies
        # Important stuff start here 👇
        - echo "$DOCKER_PASSWORD" | docker login docker.pkg.github.com -u "$DOCKER_USERNAME" --password-stdin
        - docker build -t  docker.pkg.github.com/martinheinz/go-project-blueprint/blueprint:latest .
        - docker push docker.pkg.github.com/martinheinz/go-project-blueprint/blueprint:latest
# ...

As you can see above, you can run build and push the same way as on your machine, the only difference is the docker login. Here, we use environment variables specified in Travis UI. Username gets passed to the login command through -u parameter and password using echo into stdin, this is needed, so that we don't end-up with our personal GitHub token being printed in Travis logs.

So, how do we set those environment variables? These are the steps:

Navigate to your Travis job settings for your repository e.g. https://travis-ci.com/MartinHeinz/go-project-blueprint/settings
Scroll down to Environment Variables section
Set variable name to DOCKER_USERNAME and DOCKER_PASSWORD respectively. In case of password (GitHub token) make sure, that Display value in build log is set to false.
Click Add and trigger the build

If you are not using Travis and want to use GitHub Webhook to trigger build, then you can use RegistryPackageEvent. This could be useful if you are using for example Jenkins, OpenShift or Kubernetes and want to trigger deployment every time your package is published or updated in GitHub Package Registry.

Words of Caution

One thing you should keep in mind when using GitHub Package Registry is that you can't delete packages that you push to registry. This is so that you don't break projects that depend on your package. You can request package deletion from GitHub Support, but you should not count on them actually deleting anything.

Conclusion

I hope after reading this, you will give the GitHub Package Registry a shot. If you don't have beta access yet, you can sign up here. In case you have any questions, don't hesitate to reach out to me or you can also have a look at my repository, where you can find examples of GitHub Package Registry usage.