Pushing an image to ghcr.io can be a ten-line workflow. The trouble is that a few settings are outside the workflow file, and the error messages often don't mention them. Here are six checks that cover the most common surprises, so you spend your time on the image and not on the log.

This guide is for maintainers who publish Docker images from a GitHub repository to ghcr.io.

1. The job doesn't have permission to write packages

If the push fails with permission_denied: write_package , the job probably lacks permission. Depending on your repository or organization settings, the default token permissions may be read-only.

Check: Give the publish job its own permissions block:

permissions : contents : read packages : write

Enter fullscreen mode

Exit fullscreen mode

Then log in with the built-in GITHUB_TOKEN . For a package in the same repository, you don't need a personal access token.

2. The image name has uppercase letters

Registry names must be lowercase.…