Moving to GitHub Container Registry (GHCR)

Note: Written with the help of my research and editorial team 🙂 including: (Google Gemini, Google Notebook LM, Microsoft Copilot, Perplexity.ai, Claude.ai and others as needed)

If you’re a developer working with containers, chances are Docker Hub has been your go-to for years. It’s the default, the familiar, and for many, the “it just works” solution for storing and distributing Docker images. But if you’re like me, and vibe coding, Coding Assistants has moved to doing and deploying so many of those apps you always wanted to help you with, using the free tier for personal projects or small teams, you’ve probably started bumping into some frustrating limitations.

That’s why I’m making the switch, and I believe many of you should too: I’m moving my personal projects Docker images from Docker Hub to the GitHub Container Registry (GHCR).

The Docker Hub Free Tier Dilemma: Why I’m Making the Jump

Let’s be honest: Docker Hub’s free tier has become quite restrictive for active developers.

1. The One Private Repository Trap: For solo developers or small teams, having only one private repository is a significant bottleneck. What if you have multiple microservices, internal tools, or client projects that need private image storage? You’re forced to make everything public (a bad idea for proprietary code) or upgrade to a paid plan.
2. Pull Rate Limits: This is the big one that hit me hard. With 200 pulls per 6 hours, your CI/CD pipelines, development environments, and even local testing can quickly grind to a halt. Imagine your CI pipeline failing because it can’t pull a base image, or your local docker-compose up command gets throttled during a busy day. It’s a productivity killer.

These limitations aren’t just minor inconveniences; they directly impact workflow efficiency and force difficult choices for managing private images.

Enter GHCR: The Modern, Developer-Friendly Alternative

GitHub Container Registry (GHCR) isn’t just another registry; it’s a seamless extension of the GitHub ecosystem many of us already live in. Launched in public beta on September 1, 2020, and reaching General Availability in mid-2021, GHCR was designed to address the shortcomings of traditional registries and integrate deeply with developer workflows.

Here’s why GHCR is a game-changer:

1. Unlimited Private Repositories (Yes, Really!)

This is perhaps the biggest draw for free-tier users. GHCR offers unlimited private repositories for your container images. Whether you have two projects or twenty, you can keep all your images private without hitting a paywall. This alone makes it superior to Docker Hub’s free offering.

2. Generous (and Often Non-Existent) Pull Limits

Say goodbye to “Error: You have reached your pull rate limit!” GHCR is far more lenient with pull requests. For public images, pulls are essentially unlimited. For private images, while there are theoretical limits, they are significantly higher than Docker Hub’s and typically won’t impact average usage. Crucially, pulls made by GitHub Actions within GitHub are completely free and unlimited, making it perfect for CI/CD.

3. Granular Permissions & Integration

GHCR offers superior control over who can access your images.

• Repository-Scoped Permissions: By default, an image pushed to ghcr.io/your-username/your-repo will have the same permissions as your-repo. This means if someone has access to your code, they also have access to the associated image.
• Decoupled Permissions: You can also host images independently of a specific repository and manage their access permissions separately, giving you more flexibility.
• GitHub Actions Integration: This is where GHCR truly shines. You can use the built-in GITHUB_TOKEN to authenticate your workflows, making it incredibly simple to build and push images without managing extra secrets.

4. Excellent Performance & Stability

GHCR was built to handle modern container workloads. It’s fast, reliable, and backed by GitHub’s robust infrastructure. Having been generally available since 2021, it’s a mature and trusted platform used by countless projects, including major open-source initiatives.

5. Free Tier That Actually Works

While there are some limits, they are very generous:

• Public Images: Completely free storage and data transfer.
• Private Images: You get 500MB of free storage and 1GB of free outgoing data transfer per month. For most personal projects, this is more than sufficient.
• The GitHub Actions Advantage: As mentioned, data transfer within GitHub Actions is unlimited and free, meaning your CI/CD pipelines won’t eat into your quota.

Making the Switch: A Quick How-To

Ready to move? Here’s the basic workflow:

Step 1: Create a Personal Access Token (PAT)

Go to your GitHub Settings > Developer Settings > Personal Access Tokens (Classic). Generate a new token with the write:packages and read:packages scopes. Keep this token secure!

Step 2: Log In to GHCR via Docker CLI

Bash

echo "YOUR_PAT_TOKEN" | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin

Step 3: Tag Your Image for GHCR

Replace my-node-app with your image name and your-username with your GitHub username.

Bash

docker tag my-local-image:latest ghcr.io/your-username/my-node-app:latest

Step 4: Push Your Image

Bash

docker push ghcr.io/your-username/my-node-app:latest

That’s it! Your image is now safely stored on GHCR. You can then update your deployment manifests (e.g., Kubernetes, Docker Compose) to pull from ghcr.io/your-username/my-node-app:latest.

The Future of My Containers

Moving to GHCR resolves the core pain points I experienced with Docker Hub’s free tier. The ability to host unlimited private repositories, the freedom from restrictive pull limits, and the seamless integration with GitHub Actions make it an undeniable upgrade for my workflow.

If you’re feeling constrained by Docker Hub, I highly recommend exploring GHCR. It’s a robust, feature-rich, and developer-centric registry that will likely become your new go-to.