Skip to content

GitHub Container Registry (GHCR)#

Overview#

GitHub Container Registry (GHCR) is a container image registry service provided by GitHub that allows you to store and manage Docker and OCI container images within your GitHub organization. For teams at the University of Minnesota, GHCR provides a convenient way to store container images alongside your source code, with integrated access control through GitHub's permission system.

GHCR is accessible at ghcr.io and integrates seamlessly with GitHub Actions, making it an excellent choice for CI/CD pipelines that build and deploy containerized applications.

GHCR vs. Azure Container Registry: While Azure Container Registry (ACR) is a possibly preferred option for container storage, GHCR offers some advantages and trade-offs. GHCR's primary benefit is zero cost for container image storage (currently free), whereas ACR incurs Azure charges. However, GHCR's authentication model requires GitHub Personal Access Tokens (PATs) for automation outside of GitHub Actions, which can be problematic for machine accounts and operational continuity. ACR supports more flexible authentication options like Azure Service Principals and Managed Identities. Teams should evaluate both options based on their specific workflow requirements and where their automation runs.

Key Benefits#

  • Integrated Access Control: Uses GitHub's existing permission model for authentication and authorization
  • GitHub Actions Integration: Native support for building and pushing images in your workflows
  • Public and Private Images: Support for both public container images and private images scoped to your organization
  • OCI Compliance: Supports Docker images and other OCI-compliant image formats
  • No Current Billing for Container Images: Container image storage is currently free (see Billing section for details)

Getting Started#

Authenticating to GHCR#

To push or pull images from GHCR, you need to authenticate using a GitHub token. There are two primary methods:

  1. GitHub Actions Automatic Token (Recommended for CI/CD)
  2. Personal Access Token (PAT)

Authentication Best Practices for Automated Workflows

When using GHCR in automated workflows (GitHub Actions, scheduled jobs, etc.), you should NOT use a Personal Access Token (PAT) tied to an individual person's account. If that person leaves the university or their account is deactivated, your automation will break.

Recommended Solutions:

  • For GitHub Actions: Use the built-in GITHUB_TOKEN provided automatically in workflow runs. This is the preferred method.
  • For External Automation: Add a UMN functional account (service account) to your GitHub organization and generate a PAT from that functional account. This ensures continuity when team members change.

Using GHCR in GitHub Actions#

GitHub Actions can automatically authenticate to GHCR using the GITHUB_TOKEN secret that's automatically available in every workflow run.

Here's a basic example of logging in to GHCR in a workflow:

YAML
- name: Log in to GitHub Container Registry
  uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

For a complete example of building and pushing a container image to GHCR using GitHub Actions, see our Docker Containers GitHub Actions example.

Manual Authentication with Docker CLI#

To authenticate from your local development environment:

Bash
echo $YOUR_PAT | docker login ghcr.io -u YOUR_USERNAME --password-stdin

Replace $YOUR_PAT with your Personal Access Token and YOUR_USERNAME with your GitHub username.

Setting Image Visibility#

By default, container images inherit the visibility of the repository they're linked to. You can also configure images as public or private through the package settings in your GitHub organization.

To make an image public: 1. Navigate to your organization's packages page 2. Select the container image 3. Go to "Package settings" 4. Under "Danger Zone", click "Change visibility"

Billing#

Current Pricing for Container Images#

Container image storage and bandwidth is currently free. GitHub has stated:

Billing for container image storage: Container image storage and bandwidth for the Container registry is currently free. If you use Container registry, you'll be informed at least one month in advance of any change to this policy.

If Billing Changes in the Future#

Should GitHub change their pricing policy for container images (or if you use GitHub Packages for non-container artifacts), billing would work as follows:

  1. Enterprise Free Tier: Usage would initially count against the University's enterprise-wide free usage limits:
  2. 50 GB of storage
  3. 100 GB of data transfer per month

This free tier is first-come, first-serve across all organizations in the UMN enterprise, similar to how free GitHub Actions runner minutes are shared.

  1. Paid Usage: If usage exceeds the enterprise free tier, charges are billed alongside other GitHub services (such as Copilot licenses and premium requests) to your associated Azure cost center. See the billing page for more information on cost centers.

  2. Monitoring: You can view current usage on the UMN Enterprise billing page.

Additional Resources#