Skip to main content

GitHub Container Registry (GHCR)

GitHub Container Registry (GHCR) integration allows your product to fetch container images, tags, digests, and metadata stored within GitHub's container registry (ghcr.io). This integration helps you manage container image inventories, perform vulnerability scanning, and ensure compliance across containerized workloads hosted in GitHub.

Credentials Needed​

To connect with GHCR, you need a GitHub Personal Access Token (PAT) with appropriate scopes that allow access to repositories and packages (container images).

Required credentials:

  • GitHub Username
  • Personal Access Token (PAT)

Use a Fine-grained Personal Access Token or GitHub App token with limited repository and package scopes for enhanced security.

Permissions Needed / API Scopes​

You must grant your token the following minimum scopes to read or manage images in GitHub Container Registry.

FunctionalityScopeDescription
Read container imagesread:packagesAllows reading container images, tags, and manifests
Publish container imageswrite:packagesAllows uploading or modifying images (optional)
Delete container imagesdelete:packagesAllows deleting container images (optional)
Read repositories (for private registries)repoRequired if container images are stored in private repositories
Read user dataread:userOptional — used for user context or metadata

Recommended minimal scopes for read-only integration: read:packages, repo

Creating Users / Access Tokens​

Step 1: Generate a Personal Access Token (PAT)

  1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens → Tokens (classic) or Fine-grained tokens.
  2. Click Generate new token.
  3. Select expiration (e.g., 90 days, 1 year).
  4. Under Scopes, enable:
    • read:packages
    • repo (if accessing private repositories)
    • (Optional) write:packages and delete:packages if modification is required.
  5. Click Generate Token.
  6. Copy and securely store your token — it will only be displayed once.

Test Connectivity​

You can test authentication and access using either curl or podman/docker login:

Test via Docker or Podman

# Login to GitHub Container Registry
docker login ghcr.io -u <GITHUB_USERNAME> -p <PAT>

# OR for Podman
podman login ghcr.io -u <GITHUB_USERNAME> -p <PAT>

# List images (via API or CLI)
curl -H "Authorization: Bearer <PAT>" https://ghcr.io/v2/<OWNER>/<IMAGE>/tags/list

Example

curl -H "Authorization: Bearer <PAT>" \
https://ghcr.io/v2/<GITHUB_USERNAME>/<IMAGE_NAME>/tags/list

If you get a JSON response listing image tags, your credentials and scopes are configured correctly.

Save the Results in the Platform and Create Connection​

  1. In your platform's integration configuration, securely store:
    • GITHUB_USERNAME
    • GITHUB_PAT
    • (Optional) GHCR_IMAGE_SCOPE (for specific repos or orgs)
  2. Create a new connector labeled GitHub Container Registry (GHCR) Integration.
  3. Test the connection by listing repositories or images under your GitHub account.

Best Practices​

  • Always use fine-grained tokens with read:packages scope for registry access.
  • Avoid using tokens with write:packages or delete:packages unless necessary.
  • Store tokens securely in your encrypted vault or secret manager.
  • Rotate PATs regularly (every 90 days) and remove unused tokens.
  • For organizations, prefer using GitHub Apps for scoped, revocable access instead of personal tokens.
  • Use docker login ghcr.io or podman login ghcr.io commands before performing registry operations to authenticate securely.
  • Respect GitHub API rate limits and use conditional requests (ETags) for efficient synchronization.
  • For enterprise deployments, use organization-level GHCR access policies and assign least privilege roles.