GitHub Container Registry (GHCR): free unlimited private images

Host container images alongside your code on GitHub with free unlimited private repos tied to repo permissions.

Docker HostingBeginner

Why

GHCR is free with unlimited private repos, inherits GitHub repo permissions (no separate IAM), and lives next to your source — so CI can build and deploy in one workflow without cross-registry auth. Docker is used by 59% of professional developers per the Stack Overflow 2024 survey.

Docker Hub has 15M+ public images, and OCI image spec adoption means containers run identically across Docker, Podman, and containerd.

When

Use when your code is on GitHub and you want private images without paying for Docker Hub Pro or ECR. Ideal for monorepos and org-owned images.

How

1. Enable for your account or org at github.com/settings/packages. 2. Tag as `ghcr.io/OWNER/IMAGE:tag`, login with `echo $GHCR_TOKEN | docker login ghcr.io -u USERNAME --password-stdin`, push. 3. In GitHub Actions, the `GITHUB_TOKEN` auto-authenticates to ghcr.io with packages:write permission. 4. Set package visibility to public or inherit from repo. 5. Link a package to a repo for permission inheritance.

Example

# Tag and push to GHCR docker build -t ghcr.io/myorg/myapp:1.0.0 . echo "\${GHCR_TOKEN}" | docker login ghcr.io -u myuser --password-stdin docker push ghcr.io/myorg/myapp:1.0.0 # .github/workflows/build.yml permissions: { packages: write } steps: - uses: docker/build-push-action@v5 with: registry: ghcr.io image: myorg/myapp tags: latest,${{ github.ref_name }}

Common Problems

⚠Package created under personal account instead of org — moving it requires deleting and re-pushing.
⚠GITHUB_TOKEN lacks packages:write in the workflow — add an explicit permissions: block.
⚠Public package linked to a private repo leaks the repo name in the package URL — unlink or keep private.

Best Practices

✓Use org-owned packages (ghcr.io/myorg/...) so ownership survives employee departures.
✓Inherit visibility from the linked repo so public repos get public packages automatically.
✓Clean up old tags with a scheduled GitHub Action using actions/delete-package-versions to avoid storage bloat.

FAQ

What is GitHub Container Registry (GHCR): free unlimited private images and what problem does it solve?

Host container images alongside your code on GitHub with free unlimited private repos tied to repo permissions. It lets developers deploy, store, and scale without self-managing infrastructure — a core reference for cloud service selection.

How do I get started with GitHub Container Registry (GHCR): free unlimited private images in 5 minutes?

Two steps to run it: (1) Enable for your account or org at github.com/settings/packages.; (2) Tag as `ghcr.io/OWNER/IMAGE:tag`, login with `echo $GHCR_TOKEN | docker login ghcr.io -u USERNAME --password-stdin`, push.. Validate on the free tier first, then wire into production.

What is the #1 pitfall with GitHub Container Registry (GHCR): free unlimited private images?

The most frequent issue is: Package created under personal account instead of org — moving it requires deleting and re-pushing.. Run a pre-launch checklist item by item, and add policy/config scanning in CI.

What are the best practices for GitHub Container Registry (GHCR): free unlimited private images?

Best practices for GitHub Container Registry (GHCR): free unlimited private images include: Use org-owned packages (ghcr.io/myorg/...) so ownership survives employee departures.; Inherit visibility from the linked repo so public repos get public packages automatically.; Clean up old tags with a scheduled GitHub Action using actions/delete-package-versions to avoid storage bloat.. The first one — "Use org-owned packages (ghcr.io/myorg/...) so ownership survives employee departures." — should be a team default baked into your IaC templates.

How do I control cost and avoid bill surprises with GitHub Container Registry (GHCR): free unlimited private images?

Three ways to prevent overspend: (1) tag every resource with env/team and enable billing alarms; (2) set budget thresholds to trigger Slack/email alerts; (3) review idle resources in Cost Explorer regularly and clean them up. Most GitHub Container Registry (GHCR): free unlimited private images options offer a free tier — validate within free quota before scaling.