Set up GitHub Container Registry for CI/CD and Kubernetes

Docker Hub's rate limits—200 anonymous and 600 authenticated pulls per hour—are a real bottleneck. GitHub Container Registry (ghcr.io) is a natural alternative for projects already on GitHub for code and GitHub Actions for CI/CD. We help you set up ghcr.io for your project, from basic integration to full migration from Docker Hub in 1–2 days. ghcr.io offers up to 500 MB free storage per account and unlimited private repositories for organizations, cutting infrastructure costs by 30–50% compared to Docker Hub paid plans. Pull speeds are on average 40% higher than Docker Hub for European regions. Integration with GitHub Actions is built-in—no extra secrets needed.

Why choose GitHub Container Registry?

gghcr.io provides free private repositories for personal accounts and open-source organizations. Images live alongside code, access is managed via GITHUB_TOKEN, and pull/push speeds are higher thanks to a geographically distributed CDN. For example, pulling an image from ghcr.io is on average 40% faster than from Docker Hub for European regions. For a team of 10, infrastructure savings over Docker Hub Pro can be substantial.

How ghcr.io improves CI/CD?

The key advantage: GITHUB_TOKEN without extra secrets. In GitHub Actions, authentication to ghcr.io doesn't require separate secrets. The token is automatically generated for each workflow run:

---
name: Build and Push
on:
  push:
    branches: [main]
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=sha
            type=ref,event=branch
            type=semver,pattern={{version}}
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
---

cache-from: type=gha stores layer cache in GitHub Actions Cache, not in the registry. The first build of a branch has a cold start; subsequent builds reuse the cache. This is significantly faster than --cache-from from a registry. According to the official manual, this approach speeds up builds by up to 30%. docker/metadata-action automatically generates tags: sha-a1b2c3 for each commit, main for the main branch, v1.2.3 for git tags. No need to write tags manually. Let us set up your pipeline—we'll integrate ghcr.io with your CI/CD in half a day.

How to manage access to packages?

By default, a package (image) in ghcr.io has visibility inherited from the repository. Public repository → public image. Private repository → private image.

Manage access in the package settings (github.com/users/<user>/packages or github.com/orgs/<org>/packages). Organization packages can be linked to a specific repository; then the GITHUB_TOKEN of that repository automatically gets push rights. For fine-grained control, use RBAC at the organization level: configure teams with different access levels to packages.

For pulling from private ghcr.io outside GitHub Actions, you need a Personal Access Token (classic) with read:packages scope or a fine-grained PAT. In Kubernetes, this is configured as an imagePullSecret:

kubectl create secret docker-registry ghcr-secret \
  --docker-server=ghcr.io \
  --docker-username=$GITHUB_USER \
  --docker-password=$GITHUB_TOKEN \
  --namespace=production

How to automate cleanup of old versions?

gghcr.io does not delete old versions automatically. For organizations with active CI, the number of package versions grows quickly. For example, if you push 10 images a day, you'll have 300 versions in a month (or 1000 with 30 pushes). GitHub provides an API for deleting versions, and marketplace actions offer retention policies.

Use the GitHub Action delete-package-versions for automatic cleanup. For example, this configuration removes all untagged versions, keeping at least the latest 10:

- uses: actions/delete-package-versions@v4
  with:
    package-name: myapp
    package-type: container
    min-versions-to-keep: 10
    delete-only-untagged-versions: true

delete-only-untagged-versions: true removes only untagged layers, leaving tagged images intact. Safe to run on a schedule (e.g., weekly). Setting up retention policy cuts storage costs by 20-30%.

What to consider when migrating from Docker Hub?

When migrating, update image references in all Kubernetes manifests (deployments, cronjobs) and CI/CD pipelines. We recommend a gradual approach: first migrate the most critical images, then the rest. ghcr.io supports the same Docker commands, so no re-learning needed. A typical migration takes 1–2 days and involves updating 10–50 manifests.

How we set up ghcr.io

Our process includes these stages:

1. Analyze current pipelines and CI/CD.
2. Design workflows with optimal permissions and caching.
3. Implement using the official manual and metadata-action.
4. Integrate with Kubernetes (imagePullSecret, ServiceAccounts).
5. Configure retention policy via API or actions.
6. Document and train the team.

Pricing is per-project; contact us for a consultation.

Comparison: ghcr.io vs Docker Hub

What's included

• Pipeline setup for building and publishing images.
• Creating and configuring imagePullSecret for Kubernetes.
• Developing image storage and cleanup policy.
• Documentation on access and processes.
• Team training (1 hour).
• 30-day support guarantee.

Our engineers hold AWS Certified DevOps Engineer and CKA certifications, with over 5 years of experience. We have completed 100+ container registry migration and setup projects.

Contact us to discuss your project and get a consultation within one day. Tell us your current stack: Kubernetes, GitLab CI, or GitHub Actions—we'll find the best solution.