GitHub Packages, Container Registry, Package Permissions, Provenance, and Distribution: Configuration, Design Choices, and Tradeoffs

1. Package registry versus Release asset versus Actions artifact versus external repository

Start with consumer behavior. A developer declaring an npm dependency expects semver resolution and a package registry. A Kubernetes deployment expects an OCI registry. A customer downloading one installer may prefer a Release asset. CI passing a test bundle between jobs needs an Actions artifact. A company already operating Nexus/Artifactory may need proxying, promotion repositories, retention, replication, or ecosystem breadth beyond the scope of this GitHub course.

2. Repository-linked inheritance versus granular package access

Inherited access minimizes configuration when package lifecycle follows one repository: repository readers/writers and its Actions workflows naturally align with package consumers/publishers. Granular access is useful when one package is a shared platform resource consumed by a carefully selected set of repositories independent of source-repository membership.

Granularity creates another policy object to maintain. If teams cannot answer “which repositories have package read/write/admin and why?”, the flexibility can become authorization drift. Prefer inheritance until independent package access solves a real boundary.

3. Cross-repository workflow access: explicitly grant the consumer

For a private granular package, adding packages: read to the consumer workflow is only half the configuration. Package settings must also grant that repository read access under Manage Actions access. The producer can retain write/admin while consumers get read only.

permissions:
  contents: read
  packages: read

# Registry authentication in that approved consumer job:
printf '%s' "$GITHUB_TOKEN" | docker login ghcr.io   -u "$GITHUB_ACTOR" --password-stdin

Do not grant a public repository access to a private package casually: GitHub warns that forks of that public repository may be able to access the private packages. Package access therefore participates in the fork trust model from Chapters 13 and 20.

4. Semantic version/tag for navigation; digest for immutable deployment identity

Humans need labels such as 2.4.1, stable, or latest. Automation needs a statement that survives label movement. For containers, record both:

human_selector = ghcr.io/acme/service:2.4.1
immutable_ref  = ghcr.io/acme/service@sha256:0123...cdef

A release policy can forbid moving semantic version tags after publication while still treating the digest as the cryptographic content identifier. Deployments should record the digest actually pulled, not merely the requested tag.

5. Public, private, and internal distribution are different threat models

6. Credential design: prefer workflow identity; do not broaden registry tokens by habit

Inside Actions, use GITHUB_TOKEN when the package is associated with or grants access to the workflow repository. Outside Actions, GitHub Packages registry docs use classic PAT package scopes. For automation spanning many repositories, a GitHub App may be a better GitHub API identity, but do not assume that makes its installation token a supported native registry-client login in every ecosystem.

Never place registry tokens directly in .npmrc, Dockerfiles, image layers, command history, Actions artifacts, or cache paths. If a package credential is exposed, revoke/rotate it first; deleting a config file later does not invalidate a leaked token.

7. Provenance policy: hosted, digest-pinned, attested, verified are four different states

Define maturity explicitly:

1. Hosted: bytes exist in a registry.
2. Digest-pinned: consumer can request exact bytes.
3. Attested: producer generated signed provenance binding subject name/digest to build identity.
4. Verified: consumer checked that attestation against an acceptance policy.

Skipping from “hosted” to “trusted” is a supply-chain category error. Chapter 25 will implement and verify attestations in depth.

8. Cost and retention belong in the package architecture

Public Packages usage is free. Private Packages usage has plan-specific included storage/data transfer and may incur cost beyond that allowance. GitHub currently states Container registry image storage and bandwidth are free, but the documentation also says this policy could change with advance notice. Avoid freezing a cost assumption into architecture: monitor current billing docs and define cleanup/retention by supported-version policy rather than “delete whatever is old.”

9. Worked decision: internal service platform

A platform team builds a base container used by 40 private services. The services need reproducible deployments; only the platform repository may publish; all service repositories may pull; security wants build provenance.

Knowledge check

Summary

Choose the distribution surface from the consumer lifecycle, package access from the ownership boundary, and identity from the verification requirement. Tags are ergonomic; digests are immutable content identity. Prefer short-lived workflow identity, keep visibility decisions deliberate, and do not let package hosting substitute for provenance. Next, diagnose the ways these layers fail independently.

Official references

• Package permissions
• Package access and visibility
• GitHub Packages billing
• GHES 3.21 Container registry