feat!: add registry login parameter (#292)

* feat: add registry login parameter

* docs: add usage example

* refactor: add registry login step

* fix: add default step

Author: brivu

src/commands/build_and_push_image.yml

@@ -82,33 +82,29 @@ parameters:
       false.
     type: boolean
 
-  docker_login:
-    default: false
-    description: |
-      Enable dockerhub authentication. Defaults to false.
-    type: boolean
-
-  dockerhub_username:
-    default: DOCKERHUB_USERNAME
-    description: >
-      Dockerhub username to be configured. Set this to the name of the
-      environment variable you will set to hold this value, i.e.
-      DOCKERHUB_USERNAME.
-    type: env_var_name
-
-  dockerhub_password:
-    default: DOCKERHUB_PASSWORD
-    description: >
-      Dockerhub password to be configured. Set this to the name of the
-      environment variable you will set to hold this value, i.e.
-      DOCKERHUB_PASSWORD.
-    type: env_var_name
-
   dockerfile:
     default: Dockerfile
     description: Name of dockerfile to use. Defaults to Dockerfile.
     type: string
 
+  container_registry_login:
+    description:  >-
+      Enable login to different image container registries such as
+      DockerHub, Heroku or Github. Defaults to false.
+    type: boolean
+    default: false
+
+  registry_login:
+    description:  >-
+      Custom container registry login step
+      e.g docker -u $DOCKER_ID -p $DOCKER_PASSWORD
+    type: steps
+    default:
+      - run: >-
+          echo "Error - container_registry_login parameter is set to true without
+           any registry_login steps."
+      - run: exit 1
+
   path:
     default: .
     description: >-
@@ -255,11 +251,9 @@ steps:
             public_registry: <<parameters.public_registry>>
             repo_policy_path: <<parameters.repo_policy_path>>
   - when:
-      condition: <<parameters.docker_login>>
-      steps:
-        - run: >
-            docker login -u $<<parameters.dockerhub_username>> -p
-            $<<parameters.dockerhub_password>>
+      condition: <<parameters.container_registry_login>>
+      steps: <<parameters.registry_login>>
+
   - build_image:
       registry_id: <<parameters.registry_id>>
       repo: <<parameters.repo>>

src/examples/build_and_push_image_w_registry_login.yml

@@ -0,0 +1,36 @@
+description: >
+  In some cases, images being built using the build_and_push_image job need to pull a custom
+  Docker image from a container registry like DockerHub, Heroku or GitHub Container Registry.
+  This requires users to log into these registries first before the images can be built.
+  This is an example of a using the build_and_push_image job with a custom registry login step.
+  NOTE: The container_registry_login parameter must be set to true. Registry usernames and passwords
+  are stored as environment variables in CircleCI with this example.
+
+usage:
+  version: 2.1
+
+  orbs:
+    aws-ecr: circleci/[email protected]
+    # importing aws-cli orb is required for authentication
+    aws-cli: circleci/[email protected]
+workflows:
+  build-and-push-image-with-container-registry-login:
+    jobs:
+      - aws-ecr/build_and_push_image:
+          # must set container registry login to true
+          container_registry_login: true
+          container_registry_login_step:
+            # custom login step for heroku.
+            - run: docker login -u ${HEROKU_USERNAME} -p ${HEROKU_API_KEY}
+            # custom login step for GitHub Container Registry.
+            - run: docker login -u ${GITHUB_USERNAME} -p ${GITHUB_TOKEN}
+            # custom login step for DockerHub.
+            - run: docker login -u ${DOCKERHUB_ID} -p ${DOCKERHUB_PASSWORD}
+          auth:
+            - aws-cli/setup:
+                role_arn: arn:aws:iam::123456789012
+          repo: my-sample-repo
+          tag: sampleTag
+          dockerfile: Dockerfile
+          path: .
+          region: us-west-2

src/examples/build_test_then_push_image.yml

@@ -9,7 +9,7 @@ usage:
 
   orbs:
     aws-ecr: circleci/[email protected]
-    # importing aws-cli orb is required
+    # importing aws-cli orb is required for authentication
     aws-cli: circleci/[email protected]
   jobs:
     build-test-then-push-with-buildx:

src/jobs/build_and_push_image.yml

@@ -93,27 +93,23 @@ parameters:
       Enable Docker layer caching if using remote Docker engine.
       Requires setup_remote_docker to be set to true. Defaults to false.
 
-  docker_login:
+  container_registry_login:
+    description:  >-
+      Enable login to different image container registries such as
+      DockerHub, Heroku or Github. Defaults to false.
     type: boolean
     default: false
-    description: >
-      Enable dockerhub authentication. Defaults to false.
-
-  dockerhub_username:
-    type: env_var_name
-    default: DOCKERHUB_USERNAME
-    description: >
-      Dockerhub username to be configured. Set this to the name of
-      the environment variable you will set to hold this
-      value, i.e. DOCKERHUB_USERNAME.
 
-  dockerhub_password:
-    type: env_var_name
-    default: DOCKERHUB_PASSWORD
-    description: >
-      Dockerhub password to be configured. Set this to the name of
-      the environment variable you will set to hold this
-      value, i.e. DOCKERHUB_PASSWORD.
+  registry_login:
+    description:  >-
+      Custom container registry login step
+      e.g docker -u $DOCKER_ID -p $DOCKER_PASSWORD
+    type: steps
+    default:
+      - run: >-
+          echo "Error - container_registry_login parameter is set to true without
+           any registry_login steps."
+      - run: exit 1
 
   dockerfile:
     type: string
@@ -234,9 +230,8 @@ steps:
       remote_docker_version: <<parameters.remote_docker_version>>
       workspace_root: <<parameters.workspace_root>>
       create_repo: <<parameters.create_repo>>
-      docker_login: <<parameters.docker_login>>
-      dockerhub_username: <<parameters.dockerhub_username>>
-      dockerhub_password: <<parameters.dockerhub_password>>
+      container_registry_login: <<parameters.container_registry_login>>
+      registry_login: <<parameters.registry_login>>
       public_registry_alias: <<parameters.public_registry_alias>>
       set_repo_policy: <<parameters.set_repo_policy>>
       repo_policy_path: <<parameters.repo_policy_path>>