Using GitHub Container Registry in Practice (2024)

Did you know that GitHub has launched the new GitHub Container Registry September 2020?

That’s great news for people who use GitHub packages already, as GitHub has launched many new capabilities for container users. In this article, let’s discuss the things you should know about the latest GitHub Container Registry. 😊

Here is what’s covered in this article.

• Introduction to Container Registry
• The new capabilities of GitHub Container Registry
• How to migrate to GitHub Container Registry?
• A Use Case — Deploying an Nginx webserver to Kubernetes with GitHub Actions, Kubernetes, and GitHub Container Registry.

Let’s start with a quick introduction to Container Registries. If you are already familiar with that, feel free to skip the following section.

A Container Registry is a place to store and manage container images. These container images can be either Public and Private. The Public container images are accessible by anyone, whereas you can configure access control for Private container images.

Examples of popular container registries are DockerHub, Azure Container Registry, Amazon Elastic Container Registry(ECR).

So, why do we need a container registry in the first place?

Ease of Cloud Deployment

Today most of the applications are running on the cloud. Major cloud providers support downloading container images from popular container registries to deploy applications on demand.

Ease of Container Management

The container registry also helps to centrally manage application container images efficiently across teams within your organization.

Additional Features!

Some container registries have additional features such as image scanning for vulnerabilities, geo replications for high availability, etc.

Now that we know about Container Registries, Let’s get to know about the newly announced GitHub Container Registry.

GitHub Container Registry allows organizations to seamlessly host and manage their container images with fine-grain permissions. It can store both Private and Public container images as well.

Let’s look at the following table that compares and contrasts GitHub Container Registry vs. other popular container registries.

One thing to note is that the GitHub Container Registry is currently in public beta and the pricing model for private images, General Availability and SLA are subject to change.

Prior to GitHub Container Registry, GitHub used GitHub Packages Docker Registry for storing Docker images.

However, the GitHub Container registry supersedes the GitHub Packages Docker registry and optimizes the support for containers’ unique needs by introducing many new features.

Have a look at the following new features introduced with GitHub Container Registry. You can read more about them here.

1. Ability to store container images under your organization

GitHub Container Registry allows you to create container images under your organization. Now you can easily share those container images with your teams securely.

2. Fine-grained permissions for the container images

You don’t have to issue the repository permission to container users. Instead, you can now assign the least privilege permission for the individual users. That will ensure better security for your container images.

3. Can access public container images anonymously

Some of the other container registries require authentication to access public images. But GitHub Container Registry allows you to access any public image without authentication

Let’s imagine you have docker images already in the GitHub Packages Docker registry and want to migrate them to GitHub Container Registry. How can you do that?

Well, there are a few things you should keep in mind before the migration.

GitHub Container Registry uses a new domain i.e.ghcr.io for docker images instead of the old domaindocker.pkg.github.com which is used by the GitHub Packages Docker Registry.

Have a look at the example docker image URLs below.

Example URL — GitHub Packages Docker Registry

docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME

Example URL — GitHub Container Registry

ghcr.io/OWNER/IMAGE_NAME

At the moment of this writing, GitHub Container Registry supports only PAT (Personal Access Token) to authenticate and access the container images owned by your organization.

Creating a PAT

When creating a PAT, we need to give the following permissions. Follow this documentation for more information.

• read:packages Scope to download container images and read their metadata.
• write:packages Scope to download and upload container images and read and write their metadata.
• delete:packages Scope to delete container images.

Save the PAT as an environment variable

export CR_PAT=<TOKEN>

Authenticating with GitHub Container Registry

echo $CR_PAT | docker login ghcr.io -u kasunsjc --password-stdin

Once we are authenticated, we are ready to push images to GitHub Container Registry. However, we need to tag the image before it’s pushed to the registry.

You should follow the format ghcr.io/USERNAME/IMAGENAME:TAG when tagging a container image.

docker image tag nginx:latest ghcr.io/kasunsjc/nginx:v1

After the image is built and tagged, then you are ready to push it to the registry. Use the following command to push the image to GitHub Container Registry.

docker image push ghcr.io/kasunsjc/nginx:v1

Once it’s pushed to the container registry, you can verify your image by navigating to the Packages section in the GitHub as shown below.

Now that the images are on GitHub Container Registry, how do we pull them into our local machine or to your build server?

Well, You can easily use the docker image pullcommand. Have a look at the following example of pulling an Nginx image.

Now imagine, you want to make the image that is pushed to the GitHub Container Registry public, so everyone can access it.

How can you do that?

GitHub Container Registry supports both public and private images. We can make an image public as shown below.

Note: Making an image public is NOT bidirectional, so if you decide to make an image repository public, there no way of making the image back to private.

Now that we understand about GitHub Container Registry, let’s use it with other services such as GitHub Actions and Kubernetes.

In this use case, we are going to deploy an Nginx webserver to Kubernetes. During that process, we will be using GitHub Container Registry to store the built image and GitHub actions to build and push the image to the Registry.

Have a look at the following diagram to get the overall picture of what we are going to accomplish.

Let’s use the following instructions in the dockerfile to dockerize a simple web page that is served by Nginx.

FROM nginx:latest
COPY ./index.html /usr/share/nginx/html/index.html

Then we use the following Workflow file to inform GitHub Actions to perform the listed jobs to push the image to the Container Registry and Deploy to Azure Kubernetes Service.

If you are new to GitHub Action, refer to the article below and understand it better. You can also visit this GitHub link to access the demo files.

After successful execution of the GitHub Action, the application is deployed to Kubernetes and you should see the following output.

You can now access the webpage by browsing to the Kubernetes Load Balancer IP.

You can also verify if the application is using the correct image from the GitHub Container Registry using the kubectl decribe pod command as shown below.