skip to content

Registries and Authentication

GitHub Packages is several registries behind one identity system: ghcr.io for images, plus npm, Maven, NuGet endpoints. Almost every setup problem is an auth problem — which token, which scopes, and which config file the client actually reads.

on this pageshow

questions

5

In GitHub Packages, what is the Container registry at ghcr.io, and how do you log the Docker client in to push an image there?

level: juniorimportance: must knowfreq 48%

answer

  1. images live under an account, not a repo
  2. only one kind of personal token
  3. three packages scopes
  4. password-stdin, never the password

basics

~20 s

ghcr.io is the GitHub Packages registry for Docker and OCI images, scoped to a user or organisation. Log in with docker login ghcr.io using a classic personal access token with write:packages, or GITHUB_TOKEN with packages: write inside a workflow.

solid answer

~40 s

The Container registry is the part of GitHub Packages that stores Docker and OCI images under a personal account or organisation, addressed as `ghcr.io/NAMESPACE/IMAGE:TAG`. It replaced the older Docker registry at `docker.pkg.github.com`. The only personal token GitHub Packages accepts is a **personal access token (classic)**, not a fine-grained one: `read:packages` to pull, `write:packages` to push, `delete:packages` to delete. From a laptop you pipe the token in with `docker login ghcr.io -u alice --password-stdin`; inside a GitHub Actions workflow you use `GITHUB_TOKEN` and give the job `packages: write`, so no long-lived secret is stored. One thing differs from the other GitHub Packages registries: a **public** image on ghcr.io can be pulled anonymously.

code

bash · 4 lines
bash
export CR_PAT=ghp_xxxxxxxx   # classic token with write:packages
echo "$CR_PAT" | docker login ghcr.io -u alice --password-stdin
docker tag billing-api ghcr.io/acme/billing-api:1.4.0
docker push ghcr.io/acme/billing-api:1.4.0

go deeper

for a junior

Recall that ghcr.io holds container images under an account, that GitHub Packages takes a classic personal access token, and the three packages scopes for reading, writing and deleting.

for a middle

Explain why the job token beats a personal token in a workflow, how the token form adds the repo scope, and why public images are the one anonymous case.

for a senior

Show how you keep personal tokens out of pipelines entirely, and how you diagnose a denied push by checking scope, SSO enablement and the account's role on the package.

for a principal

Weigh a shared registry identity model across npm, Maven and images against per-registry credentials, and decide where personal tokens are still tolerated and who owns their rotation.

## What the Container registry is **GitHub Packages** is GitHub's hosting service for software packages. It is not one registry but several, each speaking the native protocol of a package client. The **Container registry**, at `ghcr.io`, is the one for container images: it accepts images in the Docker Image Manifest V2, Schema 2 format and in the Open Container Initiative (OCI) image format, and it supports foreign layers such as Windows images. An image in the Container registry belongs to a **personal account or an organisation**, not to a repository. The account is the first path segment of the image name: - `ghcr.io/acme/billing-api:1.4.0` is the `billing-api` image owned by the `acme` organisation, tag `1.4.0`; - the image can optionally be **linked** to a repository, but the name alone does not do that; - when a package is first published from the command line its default visibility is **private**; who can see it afterwards is a package setting, not a property of the login. The Container registry replaced GitHub's earlier **Docker registry**, which used the host `docker.pkg.github.com`. GitHub migrated the images stored there into the Container registry automatically, and old scripts that still use the old host keep working after migration, but new work should name `ghcr.io`. ## One family of registries, one identity The same account and the same token work across every GitHub Packages registry; only the host and the client configuration file change. | Registry | Endpoint | Client reads credentials from | |---|---|---| | Container | `ghcr.io/NAMESPACE/IMAGE` | `docker login ghcr.io` | | npm | `https://npm.pkg.github.com` | `.npmrc` | | Apache Maven, Gradle | `https://maven.pkg.github.com/OWNER/REPOSITORY` | `~/.m2/settings.xml` or the Gradle build | | NuGet | `https://nuget.pkg.github.com/NAMESPACE/index.json` | `nuget.config` or `dotnet nuget add source` | | RubyGems | `https://rubygems.pkg.github.com/NAMESPACE` | gem sources or Bundler config | ## The credential: a classic personal access token Outside a workflow, the credential is a personal token, and as GitHub's documentation stood on 2026-10-06 the only kind GitHub Packages supports is a **personal access token (classic)**; a fine-grained personal access token is not accepted. The token carries one or more packages scopes, and your own account must also hold the matching role on the package: | Scope | Lets the token | Account needs | |---|---|---| | `read:packages` | download images and read their metadata | read | | `write:packages` | upload and download images, read and write metadata | write | | `delete:packages` | delete images (together with `read:packages`) | admin | Two traps sit in the token form itself: 1. Ticking `write:packages` in the web form **also selects the `repo` scope by default**, which grants broad repository access the registry does not need. The documented workaround is to open the form at `https://github.com/settings/tokens/new?scopes=write:packages`, which pre-selects only that scope. 2. If the organisation that owns the image requires **SSO**, the new token must be enabled for SSO before it can reach that organisation's packages. ## Logging in from a laptop ```bash export CR_PAT=ghp_xxxxxxxx echo "$CR_PAT" | docker login ghcr.io -u alice --password-stdin docker tag billing-api ghcr.io/acme/billing-api:1.4.0 docker push ghcr.io/acme/billing-api:1.4.0 ``` `--password-stdin` keeps the token out of the command line and shell history. Where the Docker client then stores that credential is the Docker client's own business, covered with the material on registry credentials. ## Logging in from a workflow Inside GitHub Actions the job does not need a personal token at all. It logs in to `ghcr.io` with the workflow's `GITHUB_TOKEN` as the password and the triggering user (`github.actor`) as the username, and the job declares `packages: write` (plus `contents: read` to check out the code). The token is issued per job and expires with it, which is why GitHub's documentation strongly recommends it over a stored personal token for the Container registry. ## Pulling, and the one exception In most GitHub Packages registries a token is needed even to install a **public** package. The Container registry is the exception: public images allow **anonymous** pulls, so `docker pull ghcr.io/acme/public-tool:2.0` works with no login. Private and internal images need a token with `read:packages` and an account that has read access. ## First failures to recognise - **Denied on push with a valid token**: the token lacks `write:packages`, it is not enabled for the organisation's SSO, or the account has no write role on an existing package. - **Authentication fails although the token looks valid**: an account password or a fine-grained token was used instead of a classic token. - **Upload aborted on a huge image**: the Container registry caps each layer at 10 GB and each upload at a 10-minute timeout.

  • An old deployment script in GitHub Packages still pulls from docker.pkg.github.com. Is that a problem?
    That host belonged to GitHub's retired Docker registry, which the Container registry at `ghcr.io` replaced. GitHub migrated the stored images automatically, and scripts using the old namespace keep working after migration, so it is not an outage. It is still technical debt: update the script to `ghcr.io`, where the image now lives and where granular package permissions apply.
  • In GitHub Packages, could you use a fine-grained personal access token restricted to one repository instead of a classic token?
    Not according to GitHub's documentation as of 2026-10-06: among personal tokens GitHub Packages supports only the classic kind. The least-privilege moves available are a classic token carrying only the packages scope you need, created without the `repo` scope, and, inside workflows, `GITHUB_TOKEN` instead of any personal token.
  • Your organisation in GitHub Packages enforces SSO, and a freshly created classic token cannot push to its images. What is missing?
    The token has not been enabled for the organisation's SSO. GitHub's documentation says that if the organisation requires SSO you must enable SSO for the new token; until then the token does not reach that organisation's packages, even with `write:packages` and a write role on the package.

  • A fine-grained personal access token with package permissions works for ghcr.io.
  • You log in to ghcr.io with your GitHub account password.
  • Ticking write:packages alone in the token form gives a narrowly scoped token.
  • Every pull from ghcr.io needs a token, even for a public image.
  • New images should still be pushed to docker.pkg.github.com.
open as a page

In GitHub Packages, how does Maven find the token for maven.pkg.github.com, and why must the repository id match a settings.xml server id?

level: middleimportance: should knowfreq 24%

basics

~10 s

Maven sends credentials only for a repository whose id matches a server id in ~/.m2/settings.xml; that server holds the GitHub username and a classic token, and the repository URL is https://maven.pkg.github.com/OWNER/REPOSITORY.

open as a page

In GitHub Packages, how does a project point npm at npm.pkg.github.com, and why must the package scope match the owning account?

level: middleimportance: should knowfreq 30%

basics

~10 s

GitHub Packages hosts only scoped npm packages, and the scope is the owning user or organisation, so .npmrc maps @acme to https://npm.pkg.github.com and a separate auth line supplies a classic token for that host.

open as a page

In GitHub Packages, a second private repository's workflow must install your organisation's private npm library and pull its image; how do you grant that without a personal token?

level: seniorimportance: should knowfreq 20%

basics

~10 s

On each package's settings, use Manage Actions access to add the consuming repository with the Read role; its workflow then authenticates with its own GITHUB_TOKEN. Maven and Gradle packages lack this, being repository-scoped.

open as a page