Troubleshooting Dockerhub Authentication when using Orb Executors

If you have authentication failures when using an orb executor this can be because unless an Orb has been specifically updated, it is not possible to pass Docker Hub auth parameters to the executors defined by an orb.

Each orb will need to be updated to allow the docker auth parameters to be passed - please feel free to raise an issue against the GitHub repos to bring this up with the Community team directly.

Solution

You can workaround this issue by defining the executor manually.

The following example is for the cimg/php image:

The source for the executor is shown below:

description: The official CircleCI CIMG PHP Docker image.
docker:
  - image: 'cimg/php:<< parameters.tag >>'
parameters:
  tag:
  default: '7.4'
  description: The `cimg/php` Docker image version tag.
  type: string

This executor definition in the orb is spinning up a docker image defined by a parameter.

The following config.yml example below is based on the example shown on the Docker private images guide:

version: 2.1
workflows:
  my-workflow:
    jobs:
      - build:
          context:
            - build-env-vars
            - docker-hub-creds
jobs:
  build:
    docker:
      - image: cimg/php:7.4
        auth:
          username: mydockerhub-user # can specify string literal values
          password: $DOCKERHUB_PASSWORD # or project environment variable reference

If you want to retain the parameter functionality instead of hard-coding the version you can use the following example:

version: 2.1

workflows:
  my-workflow:
    jobs:
      - build:
          phpver: "7.3.11"
          context:
            - build-env-vars
            - docker-hub-creds

jobs:
  build:
    parameters:
      phpver:
        type: string
        default: "7.4"
    docker:
      - image: cimg/php:<< parameters.phpver>>
        auth:
          username: mydockerhub-user # can specify string literal values
          password: $DOCKERHUB_PASSWORD # or project environment variable reference
    steps:
       - run: echo "Hello!"

Outcome

When running your config.yml you will no longer see the authentication issue and this can be applied to any orb executor.