Overview

When building an ephemeral Docker image, you may not necessarily want to push to a Docker registry (e.g., Docker Hub). However, you may still want a subsequent job to be able to retrieve this image.This article shows you how you can pass a built Docker image from one job to another job downstream without needing a Docker registry.

Prerequisites

This is achieved by using workspaces, and thus requires that the 2 jobs are in the same workflow.

If you need to pass Docker images between workflows, you will need to make use of caches.

Job A: Save built image as tar file

We can use the `docker image save` command to save an image as a tar file.

jobs:
  build_image:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - setup_remote_docker:
          version: 20.10.18
      - run:
          name: Build image
          command: |
            docker image build --tag "acmeorg/foobar:${CIRCLE_SHA1}" .
      - run:
          name: Save image as tar
          command: |
            mkdir -p images
            docker image save -o "images/acmeorg_foobar_${CIRCLE_SHA1}" "acmeorg/foobar:${CIRCLE_SHA1}"
      - persist_to_workspace:
          root: .
          paths:
            - images

Job B: Load built image from tar file

We then use the `docker image load` command to load an image via the tar file loaded from the workspace.

jobs:
  load_image:
    docker:
      - image: cimg/base:stable
    steps:
      - attach_workspace:
          at: .
      - setup_remote_docker:
          version: 20.10.18
      - run:
          name: Load image
          command: |
            docker image load < "images/acmeorg_foobar_${CIRCLE_SHA1}"
      - run:
          name: Inspect loaded image
          command: |
            # we should see acmeorg/foobar:${CIRCLE_SHA1} listed
            docker image ls
      - run:
          name: Use image
          command: |
            echo "TODO: run container with image"

We then would combine the 2 jobs in the same workflow.

workflows:
  sample:
    jobs:
      - build_image
      - load_image:
          requires:
            - build_image

Outcome

You should be able to have the built Docker image loaded for use in subsequent jobs in the same workflow.

Important Considerations

The saved tar files may be large. Loading and saving to workspaces can take time depending on the file sizes.
This solution is not applicable for a downstream Docker executor job trying to use this image. For Docker executor jobs, the image must be pulled from an available Docker image registry.