GitHub Container Registry Cheat Sheet

• Store, manage, and distribute Docker & OCI container images.
• Seamlessly works with GitHub repositories, GitHub Actions, and fine-grained access controls.
• Supported Formats:
  • Docker Image Manifest V2, Schema 2
  • Open Container Initiative (OCI) specifications

Features

• You can host and manage container images directly in GitHub.
• Access can be controlled either by linking to repository permissions or by defining granular package-level permissions.
• Authentication can be performed using either GITHUB_TOKEN (for workflows in the same repo) or a Personal Access Token (classic) with the appropriate scopes.
• Public images can be pulled anonymously without authentication.
• GitHub Actions can automate builds, tests, and deployments using GHCR.

Setup & Authentication

• Using GITHUB_TOKEN:
  • Provided automatically in GitHub Actions workflows.
  • Can publish packages associated with the workflow repository.
  • Can install packages if the repository has read access to the package
• You need to generate a PAT with write:packages, read:packages, and optionally delete:packages and repo scopes.
• Log in to GHCR using Docker CLI with your PAT.

  export CR_PAT=YOUR_TOKEN
  echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin

• Tag your image using the GHCR naming convention before pushing.
• Push the image to GHCR using docker push.

  docker push ghcr.io/NAMESPACE/IMAGE_NAME:latest

• Pull images from GHCR using docker pull.

  docker pull ghcr.io/NAMESPACE/IMAGE_NAME

Naming Convention

• The format for images is:

  ghcr.io/NAMESPACE/IMAGE_NAME[:TAG].

  • The NAMESPACE is your GitHub username or organization.
  • The <IMAGE_NAME> is the name of your container image.
  • The <TAG> is the version or label, such as latest or v1.0.

Permissions & Security

• Repository-linked permissions automatically inherit access from the repo.
• You can define granular permissions for specific users or teams.
• Anonymous access is allowed for public images.
• Scoped tokens should follow the principle of least privilege.

Common Use Cases

• Teams use GHCR to host private container images for internal projects.
• Open-source developers distribute public images alongside their code.
• CI/CD pipelines use GHCR with GitHub Actions for automated workflows.
• Multi-cloud deployments can centralize image hosting in GitHub.

GHCR vs Docker Hub

GitHub Container Registry Cheat Sheet Resources:

https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry
https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/run-jobs-in-a-container
https://github.blog/news-insights/product-news/introducing-github-container-registry/