setup

GitHub Container Registry

Purpose

Loads an organization's GitHub Container Registry (ghcr.io) into Subimage: container packages, image manifests and layers, tags, and SLSA attestations. Running ghcr.io/ containers from your Kubernetes clusters link to these images, and the scan module pulls them with the same token, which is what puts vulnerabilities and attack paths on those workloads.

tip

Secret fields below accept either an AWS Secrets Manager ARN or a value pasted directly into Subimage's managed vault. See Secrets for details.

Why this is separate from the GitHub module

GitHub Packages and ghcr.io authenticate only with a classic personal access token or the Actions GITHUB_TOKEN. GitHub App installation tokens and fine-grained tokens are refused both by the API that lists an organization's packages and by ghcr.io at pull time. The github module keeps authenticating everything else through the App or your existing token; this module takes the classic token the registry needs.

Required Fields

Field Secret? Description
ghcr_token Yes Classic personal access token with read:packages, plus repo for packages linked to private repositories
ghcr_orgs No GitHub organization slugs whose registry to sync, one per line or comma-separated
github_url No GraphQL API endpoint. Default https://api.github.com/graphql; set it for GitHub Enterprise Server

Setup Steps

  1. Enable the github module for the same organizations. Packages attach to the organization nodes it writes, and this module runs after it.
  2. On a service account that is a member of every organization you list, open Settings → Developer settings → Personal access tokens → Tokens (classic) and generate a token with read:packages and repo. Fine-grained tokens do not work.
  3. If the organization enforces SAML SSO, authorize the token for it (Configure SSO next to the token).
  4. In Subimage, paste the token into ghcr_token, list the organizations in ghcr_orgs, and save.

The scan module reads ghcr_token on its own when a running workload references a ghcr.io/ image. Nothing else to configure there.

Notes

  • If the github module already runs on a classic PAT with read:packages, the same token works here.
  • The sync is read-only.

Troubleshooting

  • GitHub Packages Refused — the token is not a classic PAT with read:packages, is not authorized for the organization's SAML SSO, or the organization slug is wrong.
  • GitHub Unauthorized — the token is invalid or expired.
  • No GitHubContainerImage nodes after a successful sync — the organization has no container packages, or the token's user cannot see them. Check Packages on the organization page while signed in as that user.