Using Docker Authenticated Pulls
Cloud Server v2.x Server v3.x This document describes how to authenticate with your Docker registry provider to pull images.
Authenticated pulls allow access to private Docker images. It may also grant higher rate limits, depending on your registry provider.
CircleCI has partnered with Docker to ensure that our users can continue to access Docker Hub without rate limits. As of November 1st 2020, with few exceptions, you should not be impacted by any rate limits when pulling images from Docker Hub through CircleCI. However, these rate limits may be implemented for CircleCI users in the future. This is why we are encouraging you and your team to add Docker Hub authentication to your CircleCI configuration and consider upgrading your Docker Hub plan, as appropriate, to prevent any impact from rate limits in the future.
Docker executor
For the Docker executor, specify a username and password in the auth field of your config.yml file. To protect the password, place it in a context, or use a per-project Environment Variable.
| Server 2.x customers may instead set up a Docker Hub pull through a registry mirror. Pulls through Docker Hub registry mirrors are not yet available on server 3.x. |
| Contexts are the more flexible option. CircleCI supports multiple contexts, which is an effective way to modularize secrets, ensuring jobs can only access what they need. |
This example grants the "build" job access to Docker credentials context, docker-hub-creds, without bloating the existing build-env-vars context:
workflows:
my-workflow:
jobs:
- build:
context:
- build-env-vars
- docker-hub-creds
jobs:
build:
docker:
- image: acme-private/private-image:321
auth:
username: mydockerhub-user # can specify string literal values
password: $DOCKERHUB_PASSWORD # or project environment variable referenceIf you have two-factor authentication set up on Docker Hub, you can simply use your personal access token for the password key instead. For example:
- image: acme-private/private-image:321
auth:
username: mydockerhub-user
password: $DOCKERHUB_ACCESS_TOKENYou can also use images from a private repository like gcr.io or quay.io. Ensure you supply the full registry/image URL for the image key, and use the appropriate username/password for the auth key. For example:
- image: quay.io/project/image:tag
auth:
username: $QUAY_USERNAME
password: $QUAY_PASSWORDMachine executor (with Docker orb)
Alternatively, you can utilize the machine executor to achieve the same result using the Docker orb:
version: 2.1
orbs:
docker: circleci/docker@1.4.0
workflows:
my-workflow:
jobs:
- machine-job:
context:
- build-env-vars
- docker-hub-creds
jobs:
machine-job:
machine: true
steps:
- docker/check:
docker-username: DOCKERHUB_LOGIN # DOCKER_LOGIN is the default value, if it exists, it automatically would be used.
docker-password: DOCKERHUB_PASSWORD # DOCKER_PASSWORD is the default value
- docker/pull:
images: 'circleci/node:latest'Machine executor (with Docker CLI)
Or with the CLI:
version: 2
jobs:
build:
machine: true
working_directory: ~/my_app
steps:
# Docker is preinstalled, along with docker-compose
- checkout
# start proprietary DB using private Docker image
- run: |
docker login -u $DOCKER_USER -p $DOCKER_PASS
docker run -d --name db company/proprietary-db:1.2.3AWS ECR
CircleCI now supports pulling private images from Amazon’s ECR service.
You can pull your private images from ECR repositories in any regions. However, for the best experience, we strongly recommend you make a copy of your image in us-east-1 region, and specify that us-east-1 image for the Docker executor. Our job execution infrastructure is in the us-east-1 region, so using us-east-1 images accelerates the process of spinning up your environment. |
You can start using private images from ECR in one of two ways:
-
Set your AWS credentials using standard CircleCI private environment variables.
-
Specify your AWS credentials in
.circleci/config.ymlusingaws_auth:
version: 2
jobs:
build:
docker:
- image: account-id.dkr.ecr.us-east-1.amazonaws.com/org/repo:0.1
aws_auth:
aws_access_key_id: AKIAQWERVA # can specify string literal values
aws_secret_access_key: $ECR_AWS_SECRET_ACCESS_KEY # or project UI envar referenceBoth options are virtually the same. However, the second option enables you to specify the variable name you want for the credentials. This can be useful where you have different AWS credentials for different infrastructures. For example, your SaaS app runs the speedier tests and deploys to staging infrastructure on every commit, while for git tag pushes, we run the complete test suite before deploying to production:
version: 2
jobs:
build:
docker:
- image: account-id.dkr.ecr.us-east-1.amazonaws.com/org/repo:0.1
aws_auth:
aws_access_key_id: $AWS_ACCESS_KEY_ID_STAGING
aws_secret_access_key: $AWS_SECRET_ACCESS_KEY_STAGING
steps:
- run:
name: "Every Day Tests"
command: "testing...."
- run:
name: "Deploy to Staging Infrastructure"
command: "something something darkside.... cli"
deploy:
docker:
- image: account-id.dkr.ecr.us-east-1.amazonaws.com/org/repo:0.1
aws_auth:
aws_access_key_id: $AWS_ACCESS_KEY_ID_PRODUCTION
aws_secret_access_key: $AWS_SECRET_ACCESS_KEY_PRODUCTION
steps:
- run:
name: "Full Test Suite"
command: "testing...."
- run:
name: "Deploy to Production Infrastructure"
command: "something something darkside.... cli"
workflows:
version: 2
main:
jobs:
- build:
filters:
tags:
only: /^\d{4}\.\d+$/
- deploy:
requires:
- build
filters:
branches:
ignore: /.*/
tags:
only: /^\d{4}\.\d+$/See also
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Need support?
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
