Configure GitHub Container Registry as your Docker Registry

Nowadays, people are moving away from writing code for specific Linux distributions to the containerization concept. With this technology, you package an application and all its dependencies into a single, portable unit called a container. The containers are isolated from each other and from the underlying infrastructure, which means that you can run them on any platform or operating system without worrying about compatibility issues. There are several features and benefits associated with containerization, among them are portability, scalability, consistency, efficiency etc.

Docker is one of the popular tools used to spin containers. It has several key features and benefits that make it a favourite among developers and IT professionals. These include integration(with other platforms such as CI/CD pipelines, monitoring and logging tools, and cloud platforms like AWS and Azure), security, networking, image management etc.

The container registry concept is unavoidable when dealing with containerization technology. A container registry is a repository or collection of repositories where you store and access container images. They are divided into two broad categories. These are:

• Public registries: they are used by individuals and small teams that want to spin and run registries as fast as possible. They are less secure and might cause problems such as patching, privacy, and access control for large organizations.
• Private registries: Offer advanced security features, providing the best way to incorporate security and privacy into enterprise container image storage. They can be hosted remotely or on-premise. The most popular Private Registries are Amazon Elastic Container Registry (ECR), Google Container Registry, and Azure Container Registry.

GitHub Container Registry is a public registry introduced as a feature of the popular code hosting platform GitHub in 2020. It allows users to store and manage Docker container images in a secure and easy-to-use registry. The nifty features associated with the GitHub Container Registry are:

• Automated builds: The GitHub Actions can be used to automate the building and deployment of container images, this enables developers to streamline their development workflows and reduce the risk of errors.
• Integration with GitHub: It is tightly integrated with GitHub, allowing users to use the same familiar interface and workflows to manage both their code and their container images.
• Webhooks and APIs: It provides APIs and webhooks that enable users to integrate with third-party tools and services, such as CI/CD pipelines, monitoring and logging tools, and other container management systems.
• Role-based access control: It allows users to set granular permissions and access controls for their repositories, helping to ensure that only authorized users have access to sensitive or private images.
• Public and private repositories: The registry allows users to create both public and private repositories for their container images, providing flexibility and control over who has access to their images.
• Image scanning: It provides in-built scanning tools that can help detect vulnerabilities and security issues in container images, providing an extra layer of security and protection for applications.

Here, we will learn how to configure GitHub Container Registry as your Docker Registry.

Prerequisites

For this guide, you need to have Docker installed on your system. This can be done using the guide below:

• How To Install Docker CE on Linux Systems

Once installed, ensure that your system user is added to the Docker group:

sudo usermod -aG docker $USER
newgrp docker

Verify the docker installation:

$ docker version
Client: Docker Engine - Community
 Version:           23.0.3
 API version:       1.42
 Go version:        go1.19.7
 Git commit:        3e7cbfd
 Built:             Tue Apr  4 22:05:48 2023
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          23.0.3
  API version:      1.42 (minimum version 1.12)
  Go version:       go1.19.7
  Git commit:       59118bf
  Built:            Tue Apr  4 22:05:48 2023
  OS/Arch:          linux/amd64
.......

#1. Create and Configure GitHub Account

To be able to use the GitHub Container Registry, you need to have:

• A GitHub account with your GitHub username
• A personal access token

Before we create a personal access token, you need to verify your email address. Once verified, create a personal token. This token acts as an alternative to password authentication when using the GitHub API or the command line.

Navigate to your Profile->Settings

Then navigate to Developer settings->Personal access tokens.

While here, we will create a classic personal token. You can also view the token difference by following this link.

Provide the name of the token and grant permissions before you generate the token. Once generated, copy the token.

To verify if the token is valid, use it to log in to the repo:

$ docker login ghcr.io --username github-account-username
Password: [Paste your GitHub token on this prompt]

Sample output:

#2. Build and Push Docker image to GitHub Container Registry

We can then build images and push them to the GitHub Container Registry. There are two ways of doing this:

• Using Github Action
• Push images from the local machine

a. Push Images to GitHub Container Registry using Github Action

For this option, requires you to create a code in your repository. Therefore, you need to create a new repository. For this guide we’ll name it publish-to-gcr

In the created repo, create app.js file with the below contents:

console.log("Hello, World!")

Sample Output:

Then create a docker file with the below contents:

FROM node:alpine
COPY . /app
WORKDIR /app
CMD node app.js

Sample output:

Finally, create a Git action under the Actions tab. For this guide, we will set up a new workflow.

Create a YAML file and name it docker-publish.yml with the below content:

name: publish
on:
  push:
    branches: [main]
    paths-ignore:
      - "README.md"
  pull_request:
    branches: [main]
    paths-ignore:
      - "README.md"
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Login with Github Container registry
        uses: docker/login-action@v2
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Build & Publish to Github Container registry
        run:  | 
                 docker build . --tag ghcr.io/techviewleo/hello-docker-gcr-demo:latest
                 docker run ghcr.io/techviewleo/hello-docker-gcr-demo:latest
                 docker push ghcr.io/techviewleo/hello-docker-gcr-demo:latest

In the above code, replace techviewleo with your GitHub account. So will have this file in the .github/workflows folder of our repository. Once the code has been added, click on Start commit

Once started, under Action click on Publish->Run workflow and watch the progress of the job

Once the build is complete, you have the image built and uploaded to GitHub Container Registry

b. Push images from the local machine

You can also build and push docker images from your local machine. For this guide, we will create a sample Docker image using the below file:

$ vim Dockerfile
FROM ubuntu:20.04
RUN apt-get update -y
ENV DEBIAN_FRONTEND=noninteractive 
RUN apt-get install -y gnupg apt-transport-https apt-utils wget
RUN echo "deb https://notesalexp.org/tesseract-ocr5/focal/ focal main" \
|tee /etc/apt/sources.list.d/notesalexp.list > /dev/null
RUN wget -O - https://notesalexp.org/debian/alexp_key.asc | apt-key add -
RUN apt-get update -y
RUN apt-get install tesseract-ocr -y
RUN apt install imagemagick -y
ENTRYPOINT ["tesseract"]
RUN tesseract -v

Now build the image:

docker build . -t tesseract:5

Once built, view the image:

$ docker images
REPOSITORY   TAG       IMAGE ID       CREATED         SIZE                                    
tesseract    5         201b02d76283   3 minutes ago   310MB

You can then tag the image as desired using the syntax:

docker tag image-id ghcr.io/github-account/image-name:image-version

For example:

docker tag 201b02d76283 ghcr.io/techviewleo/tesseract:5

Now push this image to GitHub Container Registry

docker push ghcr.io/techviewleo/tesseract:5

Sample Output:

#3. Pull and Use Images from GitHub Container Registry

Once the images have been pushed, you can confirm from your Github account under Your Profile -> Packages.

You can now pull and use the container images. For example, if you want to pull and use the hello-docker-gcr-demo, click on it to see the pull command.

Now use the command to pull the image to your local repo:

$ docker pull ghcr.io/techviewleo/hello-docker-gcr-demo:latest
latest: Pulling from techviewleo/hello-docker-gcr-demo
f56be85fc22e: Pull complete 
26db8b79a62b: Pull complete 
1e36a4092224: Pull complete 
d05c8e097300: Pull complete 
044aa1bf899a: Pull complete 
Digest: sha256:b9d4f8ed7df8129a1d6325105b3ef308b4124eaa5fbf8f97e134e99167bb7a62
Status: Downloaded newer image for ghcr.io/techviewleo/hello-docker-gcr-demo:latest
ghcr.io/techviewleo/hello-docker-gcr-demo:latest

Verify if the image has been pulled:

$ docker images
REPOSITORY                                  TAG       IMAGE ID       CREATED        SIZE
ghcr.io/techviewleo/hello-docker-gcr-demo   latest    ab266be0947b   11 hours ago   177MB
ghcr.io/techviewleo/tesseract               5         201b02d76283   19 hours ago   310MB
tesseract                                   5         201b02d76283   19 hours ago   310MB

Now you can spin a container with the image:

docker run ghcr.io/techviewleo/hello-docker-gcr-demo:latest

Sample Output:

Final Thoughts

Today we have learned how to configure GitHub Container Registry as your Docker Registry. You are now set to build and manage your container images either with GitHub Actions or from your command line using the Docker CLI. I hope this was helpful.

See more:

• Install and Use Trow Container Image Registry With Kubernetes
• Publish Container Images to Docker Hub / Image registry with Podman
• Install Harbor Image Registry on Ubuntu
• Setup Docker Container Registry with Podman & Let’s Encrypt SSL