GitHub Container Registry Packages and Image Identity

A container package is associated with a namespace and can be connected to a repository, but its visibility and permissions are not simply the same thing as the repository's settings. Inspect the package's current access configuration. A public source repository does not justify assuming a newly created image is public, and a repository token does not automatically have rights to every unrelated package in the organization.

For workflow publishing, use the documented GITHUB_TOKEN path where applicable and request packages: write for the publishing job. The package must also allow the workflow's repository access, particularly when updating an existing package created through another path. A personal access token may be needed for some non-workflow operations under the current registry contract, but choose the documented token type and minimal scopes rather than copying a broad account token into every workflow. Do not log credentials or include them in an image layer.

GHCR image paths use a registry host and namespace followed by a package name. Lowercase the reference where the registry's naming contract requires it; the demonstration derives a lowercase repository name and appends lesson-demo to make its teaching purpose clear. Do not overwrite an established production image while learning. Choose a tag that identifies the source revision, and record the package path so consumers know which artifact belongs to the intended project.

The org.opencontainers.image.source label records the source repository URL and helps connect image metadata to its origin. It does not cryptographically prove the image was built from that repository. Preserve the source revision, build logs and any provenance or signing evidence required by your release process. A useful package review checks both metadata and actual access: which workflow can push, who can pull and whether anonymous access is intended. Keep those decisions separate from the readable image name.

A tag such as sha-<commit> is a convention, not an inherent immutability guarantee. An authorized publisher can potentially move a tag unless a policy prevents it. A digest identifies particular image content, which makes it useful when a deployment must consume the verified image rather than whichever content a tag points to later. After publishing, inspect and record the registry-reported digest under your release process.

Digest pinning alone does not establish that the image is safe or from a trusted build. Verify the source, build inputs and applicable provenance before adopting that digest. Likewise, pinning a base image to a reviewed digest improves input identity but still needs updates when the base changes. The small demonstration uses a versioned BusyBox tag to keep the example readable and explicitly does not claim reproducible or permanently fixed base bytes. A production workflow should use its reviewed base-input policy.

The workflow builds one image from a complete inline Dockerfile, logs in with password-stdin and pushes only its explicit package reference. The manual trigger avoids publishing on every untrusted contribution. For a real project, replace the inline demonstration with reviewed source and meaningful tests, then promote the exact verified artifact. Do not automatically execute fork-controlled build instructions with a publishing token or production deployment credentials.

Plan for failed pushes, access changes and package retention. A registry login can succeed while the package update is denied, because authentication and authorization are different checks. Inspect both workflow permissions and package access rather than increasing all token scopes immediately. Record the resulting digest and verify a pull in an appropriately authorized environment. If deleting old packages or changing visibility, review the consumers that depend on them first; those are operational changes beyond merely building a local image.

Read Actions, releases and security. Consult GitHub's container registry guide, package permissions and publishing tutorial, plus Docker's pull reference and Dockerfile reference.