GitHub Container Registry

What GitHub Container Registry actually is

GitHub Container Registry (ghcr.io) is GitHub's container image registry, part of GitHub Packages. It arrived in private beta in November 2019, opened as a public beta on September 1, 2020, and reached general availability on June 21, 2021, at which point GitHub consolidated its older Docker registry (docker.pkg.github.com) into it. That legacy registry was retired on February 24, 2025, so ghcr.io is now the only GitHub destination for container images.

The pitch is proximity: your images live next to the code that builds them, under the same account, permissions model, and organization structure. Images can be owned by a user or an organization, carry visibility settings independent of their source repository (public, private, or internal to an organization), and be granted fine-grained package-level permissions where inherited repository permissions don't fit. Anonymous pulls work for public images — no token needed — which is why a large share of open-source projects now distribute via ghcr.io. GitHub reported many millions of downloads per day by the time of the GA announcement.

Format support covers Docker Image Manifest V2 Schema 2, OCI image specs, and foreign layers such as Windows base layers, so multi-architecture manifests and standard tooling (docker buildx, oras, Helm OCI charts) work as expected. The GitHub Actions integration is the other half of the value: workflows authenticate with GITHUB_TOKEN, there are starter workflows for publishing directly to ghcr.io, and images get package landing pages with version and download information. Security tooling hooks in through GitHub Advanced Security and third-party scanners — Snyk integration dates from 2021, and Actions-based scanning options include Sysdig.

Pricing: what you really pay

The pricing story is the most interesting thing about GHCR, and the nuance matters.

Public packages are free: storage and data transfer for public container images cost nothing, permanently. For open-source maintainers distributing large multi-arch images to a global audience, this is one of the best deals in infrastructure — comparable to Docker Hub's open-source program without the application process.

Private packages sit under the standard GitHub Packages quotas: GitHub Free gets 500 MB of storage and 1 GB of data transfer per month, GitHub Pro and Team get 2 GB and 10 GB, and Enterprise Cloud gets 50 GB and 100 GB. That storage is shared with GitHub Actions artifacts and caches, so a CI pipeline that hoards build artifacts eats the same allowance as your images. Downloading private packages inside GitHub Actions workflows is free; pulling them out to external clouds or developer laptops consumes the transfer allowance.

The catch, and it's in GitHub's own billing documentation: container image storage and bandwidth for the Container registry are currently free, with a pledge that users get at least one month's notice before that policy changes. So today, private GHCR images don't actually burn your plan quota the way the general Packages rules suggest — a contradiction between the general quota table and the container-specific carve-out that we've flagged in our notes. Before betting a large private image estate on GHCR, verify which policy is in force that month.

Beyond included quotas, GitHub Packages usage is metered, and billing dashboards let you set spending limits to cap overage. GitHub's Actions minutes pricing and plan costs are the rest of the bill — GHCR itself is not a line item for most users right now.

Performance & infrastructure

GitHub doesn't publish PoP counts or region placement for ghcr.io the way dedicated registries and CDNs do, so our usual infrastructure columns stay empty here. What's checkable is the operational record: ghcr.io sits behind GitHub's own distribution infrastructure, anonymous pulls scale to very large public projects, and pull-through is generally fast in North America and Europe; users in other regions report more variable latency than they'd get from a registry with published regional endpoints.

Reliability is GitHub's reliability. The platform's status history includes notable multi-hour incidents affecting packages along with the rest of github.com — GitHub is not in the business of publishing per-registry SLAs, and no uptime commitment applies to ghcr.io. For most development workflows that's tolerable (a CI retry handles a blip); for production clusters pulling images at deploy time, our view is that you should run a pull-through cache or mirror regardless of which registry you use.

Feature-wise, the registry covers the modern baseline: immutable tags can be enforced at the organization level, retention rules and deletion APIs exist for cleanup, and linked repositories give you provenance context. What it lacks compared with purpose-built registries: geo-replication controls, granular regional placement, and the deeper promotion/signing policy engines of Harbor or Artifactory. If your threat model needs in-registry image signing workflows with policy enforcement, GHCR is a component rather than a complete answer — pair it with cosign or similar tooling.

Two operational details worth knowing before you migrate. First, visibility and ownership can trip teams up: a package's visibility is independent of its repository's visibility, and organization-owned packages inherit organization permissions rather than repository ones unless you grant package-level access explicitly. Getting this wrong shows up as either an image nobody can pull or one that everyone can. Second, cleanup is on you. Published images and their layers accumulate until deleted, and while GitHub exposes deletion APIs and org-level tag immutability, there is no aggressive default retention policy quietly tidying after your CI. Teams with a high build cadence should wire deletion of untagged manifests into their pipeline early; retrofitting cleanup after a year of nightly builds is a miserable afternoon.

A note on how we'd compare it with the obvious alternative, Docker Hub. Hub has the larger anonymous ecosystem and a longer history of rate-limit friction for anonymous pulls; GitHub trades anonymous pull quotas for account-scoped distribution and CI integration. If your users are other developers with GitHub accounts, ghcr.io is the smoother path. If your users are servers pulling at scale with no identity, price both carefully — GitHub's free public bandwidth is the deciding factor for most projects we see.

Where it falls short

The private-storage quota is small and shared. 500 MB on the Free plan, pooled with Actions artifacts, disappears quickly once CI builds images; the container-specific "currently free" carve-out softens this today, but it's a policy, not a commitment — GitHub can change it with a month's notice. That's the single biggest planning risk here.

Second: no published SLA and no published regional architecture. Teams with residency requirements or hard uptime targets can't get contractual answers from GHCR alone. Enterprise buyers with such requirements usually end up comparing Harbor, ECR, ACR, or Artifact Registry anyway.

Third: the registry feature set is deliberately simple. Retention and cleanup are improving but have historically lagged Docker Hub and the cloud registries; untagged image and layer accumulation is something active projects have to manage deliberately. And while permissions are fine-grained, the interaction between repository permissions, package permissions, and organization visibility takes real reading to get right.

Finally, ecosystem gravity cuts both ways. GHCR is frictionless if you live in GitHub; less so if your supply chain spans GitLab or Bitbucket, where token and workflow integration is bolted on rather than native.

Who should pick this

Our pick for open-source maintainers first — free public image storage and bandwidth with anonymous pulls is the strongest offer in /category/container-platforms for public distribution. It's equally strong for GitHub-centric teams that want images, code, CI, and permissions in one place: the GITHUB_TOKEN workflow removes an entire class of credential management.

Private-image teams should adopt it with eyes open: keep images reasonably small, enable retention policies, set a spending limit, and treat the free-private-storage policy as temporary until GitHub says otherwise. For production pull paths, put a cache in front.

Skip it if you need contractual uptime guarantees, regional data residency, or heavyweight promotion workflows — those point at the cloud-provider registries or self-hosted Harbor instead.

Key takeaways

• GitHub's container registry at ghcr.io: public beta September 2020, GA June 2021; the legacy docker.pkg.github.com registry retired February 2025
• Public images: free storage and bandwidth, anonymous pulls — the best deal going for open-source distribution
• Private quotas are small (500 MB storage / 1 GB transfer on Free, shared with Actions), but container image storage is currently free by policy with one month's promised notice before any change
• Deep GitHub Actions integration (GITHUB_TOKEN, starter workflows), OCI-compliant, fine-grained package permissions and internal visibility
• No published SLA or region placement; GitHub's own outage history applies
• Best for GitHub-centric teams and OSS maintainers; pair with a pull-through cache for production and re-check the storage policy before large private commitments

Sources

• https://docs.github.com/en/billing/managing-billing-for-github-packages/about-billing-for-github-packages
• https://github.blog/news-insights/product-news/github-packages-container-registry-generally-available
• https://en.wikipedia.org/wiki/GitHub
• https://grokipedia.com/page/GitHub_Container_Registry
• https://deploycue.com/providers/github-container-registry/review