Authenticating to the Chainguard Registry (cgr.dev)

This article covers how to authenticate to the Chainguard registry at cgr.dev. There are two authentication paths: interactive login for local development, and pull tokens for CI/CD pipelines and automated environments.

Interactive authentication (local development)

For pulling images on your local machine, use chainctl:

# Step 1: Log in to Chainguard
chainctl auth login

# Step 2: Configure Docker to use Chainguard credentials
chainctl auth configure-docker

Both steps are required. Running only chainctl auth login does not automatically configure Docker. You must also run chainctl auth configure-docker to register the credential helper with your Docker config.

After running both commands, docker pull cgr.dev/<your-org>/<image> will work without additional flags.

If you see Identity not found, re-run both commands. If credentials feel stale or you see unexpected errors, reset with:

chainctl auth logout
chainctl auth login
chainctl auth configure-docker

Note: Running sudo docker pull uses a different credential store than your user account. If you authenticated as a regular user but pull with sudo, re-run docker login as root or use sudo chainctl auth configure-docker.

Pull tokens (CI/CD and automated environments)

For pipelines, Kubernetes clusters, and any environment where interactive login isn't possible, use a pull token.

Creating a pull token:

Option A: Chainguard Console (recommended)

1. Go to console.chainguard.dev
2. Navigate to Settings > Pull Tokens
3. Create a new token and copy the username and password

Option B: CLI

chainctl auth configure-docker --pull-token --save --ttl=8760h

Using a pull token with Docker:

docker login cgr.dev --username <token-username> --password <token-password>

Using a pull token in Kubernetes:

Pull tokens use standard Docker registry credentials. Create an imagePullSecret with the correct type:

kubectl create secret docker-registry chainguard-pull-secret \
  --docker-server=cgr.dev \
  --docker-username=<token-username> \
  --docker-password=<token-password>

The secret type must be kubernetes.io/dockerconfigjson. Using Opaque type will cause 401 errors even if the credentials are correct.

Reference the secret in your pod spec:

imagePullSecrets:
  - name: chainguard-pull-secret

Using a pull token with Helm OCI charts:

Kubernetes imagePullSecrets only cover pod image pulls and do not cover helm install from an OCI registry. You must authenticate Helm separately:

helm registry login cgr.dev \
  --username <token-username> \
  --password <token-password>

Troubleshooting common errors

Listing and managing pull tokens

To see active pull tokens and check expiration dates:

chainctl iam identities list -ojson | jq '.[] | select(.name | contains("pull-token")) | {name: .name, expiry: .chainguard.expiration}'

Pull tokens have a TTL set at creation. Expired tokens silently fail. If a pipeline that was working suddenly starts returning 401s, check whether the token in use has expired.

GitHub Actions (OIDC / assumable identities)

For GitHub Actions, the recommended approach is an assumable identity (OIDC), which eliminates the need to store long-lived pull token credentials as secrets. See the Chainguard Academy for setup instructions.

When to open a support ticket

Open a ticket if:

• You have completed all steps above, and still receive 401/403 errors
• Your identity is linked to the correct org in the Console, but you still cannot pull images
• You need help configuring assumable identities for a CI/CD platform