How to Use a Docker Executor with Registry Auth in CircleCI

The Docker executor can pull private or rate-limited images by attaching auth: credentials sourced from project environment variables.

Add an auth: block under the image in the docker: list, referencing username and password from project env vars so the pull is authenticated.

Authenticated image pull

Credentials come from project env vars, never hardcoded in the config.

version: 2.1
jobs:
  build:
    docker:
      - image: my-org/private-node:20
        auth:
          username: ${DOCKERHUB_USER}
          password: ${DOCKERHUB_PASS}
    steps:
      - checkout
      - run: npm ci && npm test

Gotchas

• Set DOCKERHUB_USER/DOCKERHUB_PASS as project or context env vars; never put them in the YAML.
• Authenticated Docker Hub pulls have far higher rate limits than anonymous ones.
• Each private image in the docker: list (primary and services) needs its own auth: block.

Key takeaways

• Add auth: under a private image to authenticate the pull.
• Source credentials from env vars, not the config file.
• Authenticated pulls avoid Docker Hub anonymous rate limits.

Related guides