TutorialsLast Updated Oct 26, 202612 min read

Using CircleCI workflows to replicate Docker Hub automated builds

Jonathan Cardoso

Full-Stack Developer and DevOps Specialist at Croz.io

CircleCI workflows can be used to make your deployment process simple and intuitive. For years, Docker Hub’s automated builds were the easy way to turn a push to GitHub into a published image. Docker stopped offering them on its free tier in June 2021, so they need a paid Pro, Team, or Business subscription, and Docker has since deprecated the feature. It’s scheduled to be fully retired on April 1, 2027.

Docker’s migration guide covers moving to GitHub Actions or Bitbucket Pipelines. In this tutorial, we will learn how to do the same job with CircleCI workflows: build the image on every push, publish it to Docker Hub as latest from the main branch, and publish a version tag for every Git tag that starts with v, while keeping full control of the build process.

Prerequisites

To follow along, we need:

  • Docker installed locally
  • A GitHub account and a repository for this project
  • A CircleCI account connected to GitHub
  • A Docker Hub account (a free Personal account is enough for this tutorial)

CircleCI workflows

A workflow is a set of rules for defining a collection of jobs and their run order. - CircleCI Workflows Documentation

In our workflow, every push builds the image. Pushes to the main branch also publish it to Docker Hub with the latest tag, and every Git tag that starts with v is published as a matching image tag. Finally, we will look into how to use CircleCI’s built-in environment variables to automatically publish incremental versions of our images instead of using Git tags.

Building a Docker image

Let’s start with a basic Docker image that just prints the arguments passed when it is run. The Dockerfile will look as simple as this:

FROM alpine:3.24.2

ENTRYPOINT [ "echo" ]

Building and running the image locally should show us that it is working correctly:

$ docker build -t building-on-ci .

BuildKit, Docker’s default builder, prints its progress as it works, including a line that names the image docker.io/library/building-on-ci:latest. Then we can run the image:

$ docker run building-on-ci "Hello!"
Hello!

Building the image on CircleCI

Now that the image builds locally, we want CircleCI to build it for us.

To start building our image on each commit, we are going to bootstrap our project with the following config file. In the project’s root directory, create a .circleci directory and save the following lines as config.yml:

version: 2.1

jobs:
  build:
    environment:
      IMAGE_NAME: building-on-ci
    docker:
      - image: cimg/base:2026.10
    steps:
      - checkout
      - setup_remote_docker
      - run:
          name: Build Docker image
          command: docker build --no-cache -t $IMAGE_NAME:latest .

workflows:
  build-and-publish:
    jobs:
      - build

We are using a pre-built Docker image available from CircleCI called cimg/base:2026.10 to run our build. CircleCI has many custom images on Docker Hub that extend the official images with extra tools that are useful in a CI/CD environment. cimg/base is published as monthly snapshots tagged by date, so pinning one keeps our builds repeatable, while cimg/base:current always points to the newest snapshot. Check the CircleCI images docs for more information.

There is also an environment variable called IMAGE_NAME which we are going to use to set the name of our Docker image. It holds a plain local name. When we publish the image, we’ll put our Docker Hub username in front of it, so the config doesn’t hard-code anyone’s account.

For now, our config has a single workflow called build-and-publish that runs a single build job whenever we push a commit, on any branch. This job simply builds our Docker image and does nothing more.

One of our steps is called setup_remote_docker and is one of the most important ones when building Docker images on CircleCI. Our job steps run inside a Docker container that has the Docker CLI but no Docker Engine, so on their own they can’t build images. The setup_remote_docker step gives the job a Docker Engine to run those commands. Despite the name, that engine runs on the same virtual machine as the job’s container; “remote” is a leftover from when CircleCI created a separate environment for it. Check the building Docker images docs for more information.

Commit the changes and push the project to GitHub. Then log in to CircleCI and add the project. The steps depend on the organization’s type, which its URL in the CircleCI web app shows: /circleci/ for the CircleCI GitHub App, and /github/ or /gh/ for the GitHub OAuth app.

  • GitHub App: on the Home page, select Create project, give the project a name, and select Next. Name the pipeline and choose the repository. The first time, select the GitHub Cloud tile, and CircleCI redirects to GitHub to install the CircleCI GitHub App. Keep the default trigger, which runs a pipeline on every push. CircleCI then shows the .circleci/config.yml we just pushed. Select Review and check the setup.
  • GitHub OAuth: select Projects in the sidebar, find the repository, and select Set up. Choose Fastest to use the .circleci/config.yml already in the repository, enter main as the branch, and select Set Up Project.

The create a project docs cover both flows in more detail. Once the project is set up, CircleCI runs the build job. On the GitHub App flow, push a new commit if no pipeline has started yet.

Publishing an image to Docker Hub with the :latest tag on every commit to main

Now that we are building our image on every commit, we need to create a new job that also publishes it to Docker Hub when the commit is on main.

To push to Docker Hub from a CI job, we need credentials. Instead of our account password, we’ll use a Docker Hub personal access token (PAT): we can limit what it’s allowed to do and revoke it without changing the password. To create one, sign in to Docker Home, select the avatar in the top-right corner, then select Account settings > Personal access tokens > Generate new token. Give the token a description, set its repository permission to Repo Read & Write so it can push images, and select Generate. Docker shows the token only once, so copy it before leaving the page.

To push to an organization’s namespace instead, use an organization access token (available with Docker Team and Business) and the organization name as the username.

Whichever credential we use, it shouldn’t appear in clear text in the config file, where anyone who can read the repository would see it. We need to create new CircleCI environment variables with our username and token. There are multiple ways to do that in CircleCI, but if multiple projects are going to push images to Docker Hub, the recommended way is to use Contexts. Otherwise, we can set them directly in the project settings. For this article we are going with the latter method.

In CircleCI, open Project Settings for the project from the … menu in the project’s row on the Projects page (or, on the project’s Pipelines page, select Project, then Project settings), select Environment Variables, and then Add. Add two variables: DOCKERHUB_USERNAME, set to our Docker Hub username, and DOCKERHUB_TOKEN, set to the access token.

Our publish job will log in with this command:

echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin

Passing the token through --password-stdin, instead of the -p flag, keeps it out of the shell history and log files.

After setting the environment variables DOCKERHUB_USERNAME and DOCKERHUB_TOKEN, let’s create our job:

version: 2.1

jobs:
  build:
    environment:
      IMAGE_NAME: building-on-ci
    docker:
      - image: cimg/base:2026.10
    steps:
      - checkout
      - setup_remote_docker
      - run:
          name: Build Docker image
          command: docker build --no-cache -t $IMAGE_NAME:latest .
  publish-latest:
    environment:
      IMAGE_NAME: building-on-ci
    docker:
      - image: cimg/base:2026.10
    steps:
      - setup_remote_docker
      - run:
          name: Publish Docker image to Docker Hub
          command: |
            echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin
            docker tag $IMAGE_NAME:latest $DOCKERHUB_USERNAME/$IMAGE_NAME:latest
            docker push $DOCKERHUB_USERNAME/$IMAGE_NAME:latest

workflows:
  build-and-publish:
    jobs:
      - build
      - publish-latest:
          requires:
            - build
          filters: pipeline.git.branch == "main"

We added a new publish-latest job to the build-and-publish workflow. It runs after build, and its expression-based filter, pipeline.git.branch == "main", limits it to commits on main. The job logs in, tags the image with our Docker Hub namespace ($DOCKERHUB_USERNAME/building-on-ci), and pushes it. However, if we commit that change and check the build log, we will see that it fails:

Error response from daemon: No such image: building-on-ci:latest

The failed Publish Docker image to Docker Hub step of the publish-latest job in the build-and-publish workflow on main in CircleCI, where Login Succeeded is followed by Error response from daemon: No such image: building-on-ci:latest

This happens because the jobs in a workflow are isolated from each other: each job gets its own Docker Engine, so the image we built in the build job doesn’t exist in publish-latest.

Note the duplication we have in our configuration file. We are repeating ourselves two times with the environment variable IMAGE_NAME definition and the Docker image that is going to be used to run our jobs.

One way we could use to solve the duplication issue is by using YAML anchors. However, version 2.1 config lets us reuse configuration directly by specifying a reusable executor. At the top of the file, below version: 2.1, we are going to add a new executors key:

version: 2.1
executors:
  docker-publisher:
    environment:
      IMAGE_NAME: building-on-ci
    docker:
      - image: cimg/base:2026.10

Now on each job, instead of declaring docker and environment keys, we are going to specify a single executor key:

# ...
jobs:
  build:
    executor: docker-publisher
    # ...
  publish-latest:
    executor: docker-publisher
    # ...

Duplication resolved. Time to fix the issue with our Docker image not being available on the publish-latest job. We are going to use workspaces to share the image between the two jobs.

Let’s add a new run step at the end of the build job. This run step is going to save the image as a tar archive:

# ...
- run:
    name: Archive Docker image
    command: docker save -o image.tar $IMAGE_NAME:latest
# ...

Now, we can persist that file on the workflow workspace by adding another step called persist_to_workspace:

# ...
- run:
    name: Archive Docker image
    command: docker save -o image.tar $IMAGE_NAME:latest
- persist_to_workspace:
    root: .
    paths:
      - image.tar
# ...

To retrieve the image.tar file on the publish-latest job, we are going to add a new step, attach_workspace, before the others:

# ...
steps:
  - attach_workspace:
      at: /tmp/workspace
  # ...

And load our archived image with docker load just before we try to push it to the Docker Hub registry:

# ...
- run:
    name: Load archived Docker image
    command: docker load -i /tmp/workspace/image.tar
# ...

Our full configuration file looks like this:

version: 2.1

executors:
  docker-publisher:
    environment:
      IMAGE_NAME: building-on-ci
    docker:
      - image: cimg/base:2026.10

jobs:
  build:
    executor: docker-publisher
    steps:
      - checkout
      - setup_remote_docker
      - run:
          name: Build Docker image
          command: docker build --no-cache -t $IMAGE_NAME:latest .
      - run:
          name: Archive Docker image
          command: docker save -o image.tar $IMAGE_NAME:latest
      - persist_to_workspace:
          root: .
          paths:
            - image.tar

  publish-latest:
    executor: docker-publisher
    steps:
      - attach_workspace:
          at: /tmp/workspace
      - setup_remote_docker
      - run:
          name: Load archived Docker image
          command: docker load -i /tmp/workspace/image.tar
      - run:
          name: Publish Docker image to Docker Hub
          command: |
            echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin
            docker tag $IMAGE_NAME:latest $DOCKERHUB_USERNAME/$IMAGE_NAME:latest
            docker push $DOCKERHUB_USERNAME/$IMAGE_NAME:latest

workflows:
  build-and-publish:
    jobs:
      - build
      - publish-latest:
          requires:
            - build
          filters: pipeline.git.branch == "main"

Everything should be green now! In the job output, CircleCI masks the values of project environment variables, so our Docker Hub username shows up as a row of asterisks in image names.

Now, we can retrieve and run our image from the Docker Hub registry. On our own machine, DOCKERHUB_USERNAME isn’t set, so we export it first:

$ export DOCKERHUB_USERNAME=your-docker-hub-username
$ docker run $DOCKERHUB_USERNAME/building-on-ci "Workflows are awesome!"

Docker pulls the image from Docker Hub and runs it, which prints Workflows are awesome!.

Publishing Git tags as Docker image tags on Docker Hub

Depending on an image with latest tag can easily cause confusion since we don’t have control over which version of the image we are running. The recommended way is to use a specific tag.

Suppose we are going to use Git tags to release new versions of our Docker image, and we want CircleCI to publish our image with each Git tag as an image tag on Docker Hub. Here is how we can do it.

CircleCI doesn’t run a job for a Git tag unless the job has a filter that matches the tag, and the same goes for every job it requires (Executing workflows for a Git tag). So we need two changes to our workflow: a new publish-tag job that runs only for tags starting with v, and a wider filter on build so that it runs for those tags, too:

# ...
workflows:
  build-and-publish:
    jobs:
      - build:
          filters: pipeline.git.branch or (pipeline.git.tag matches /^v.*/)
      - publish-latest:
          requires:
            - build
          filters: pipeline.git.branch == "main"
      - publish-tag:
          requires:
            - build
          filters: pipeline.git.tag matches /^v.*/

In a pipeline triggered by a tag, pipeline.git.branch is empty and pipeline.git.tag holds the tag name. In a pipeline triggered by a branch push, it’s the other way around. That means build still runs for every branch and now also runs for v tags, publish-latest stays limited to main, and publish-tag runs only for v tags.

The publish-tag job is almost the same as publish-latest:

# ...
publish-tag:
  executor: docker-publisher
  steps:
    - attach_workspace:
        at: /tmp/workspace
    - setup_remote_docker
    - run:
        name: Load archived Docker image
        command: docker load -i /tmp/workspace/image.tar
    - run:
        name: Publish Docker image to Docker Hub
        command: |
          echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin
          IMAGE_TAG="${CIRCLE_TAG#v}"
          docker tag $IMAGE_NAME:latest $DOCKERHUB_USERNAME/$IMAGE_NAME:latest
          docker tag $IMAGE_NAME:latest $DOCKERHUB_USERNAME/$IMAGE_NAME:$IMAGE_TAG
          docker push $DOCKERHUB_USERNAME/$IMAGE_NAME:latest
          docker push $DOCKERHUB_USERNAME/$IMAGE_NAME:$IMAGE_TAG

# ...

The difference between this job and publish-latest is that this job uses an environment variable set automatically by CircleCI called CIRCLE_TAG. We retrieve the value and remove the v prefix with ${CIRCLE_TAG#v}, e.g., v0.0.1 becomes 0.0.1. We then proceed to tag our image with that version and push it to the Docker Hub Registry. We also make sure to push the latest tag, too, so that both are kept in sync. If we commit a tag we can see it working:

$ git tag v0.0.1 && git push origin v0.0.1

It’s best to push tags one at a time. When a single push carries several tags, CircleCI may not receive all of them. On projects connected through the GitHub App, the default All pushes trigger covers tag pushes, too.

For the v0.0.1 tag, CircleCI runs build and then publish-tag. publish-latest doesn’t run, because its filter only matches main:

The pipeline for the v0.0.1 tag in CircleCI, where the build-and-publish workflow ran the build and publish-tag jobs successfully

And if we access the Docker Hub page for the image, we can see the 0.0.1 tag there, next to latest. The screenshot also shows a 0.0.7 tag, which comes from the per-build tags we’ll add in the next section:

The Tags tab of the building-on-ci repository on Docker Hub, listing the 0.0.1, latest, and 0.0.7 tags with a docker pull command for each

Now, we can run our image using our tag, with the DOCKERHUB_USERNAME variable we exported earlier:

$ docker run $DOCKERHUB_USERNAME/building-on-ci:0.0.1 "Tags are working!"

Docker pulls the 0.0.1 image and prints Tags are working!.

Automatic image tags for each build

What if we have an image that we don’t use frequently or one that we don’t want to use git tags for? An image that we want to have strict control over which version we are using, so we can’t rely on the latest tag?

CircleCI allows us to do exactly that: it exposes an environment variable called CIRCLE_BUILD_NUM, the number of the current job, which goes up with every job the project runs. Using it, we can let CircleCI publish a new version of the image for every build. Let’s modify our publish-latest job to do exactly that:

# ...
- run:
    name: Publish Docker image to Docker Hub
    command: |
      echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin
      IMAGE_TAG="0.0.${CIRCLE_BUILD_NUM}"
      docker tag $IMAGE_NAME:latest $DOCKERHUB_USERNAME/$IMAGE_NAME:latest
      docker tag $IMAGE_NAME:latest $DOCKERHUB_USERNAME/$IMAGE_NAME:$IMAGE_TAG
      docker push $DOCKERHUB_USERNAME/$IMAGE_NAME:latest
      docker push $DOCKERHUB_USERNAME/$IMAGE_NAME:$IMAGE_TAG

# ...

We are using CIRCLE_BUILD_NUM to create the image tag and publishing it alongside the latest tag to Docker Hub Registry. Every job in the project takes a number, build included, so the versions skip numbers, but each one is unique. If we commit that to main and wait for the workflow to finish, the Tags tab of the image’s Docker Hub repository lists the new 0.0.<number> tag next to latest, like 0.0.7 in the earlier screenshot.

The complete configuration

Here is the complete .circleci/config.yml, with all three jobs. It’s the same file that’s in the example repository:

version: 2.1

executors:
  docker-publisher:
    environment:
      IMAGE_NAME: building-on-ci
    docker:
      - image: cimg/base:2026.10

jobs:
  build:
    executor: docker-publisher
    steps:
      - checkout
      - setup_remote_docker
      - run:
          name: Build Docker image
          command: docker build --no-cache -t $IMAGE_NAME:latest .
      - run:
          name: Archive Docker image
          command: docker save -o image.tar $IMAGE_NAME:latest
      - persist_to_workspace:
          root: .
          paths:
            - image.tar

  publish-latest:
    executor: docker-publisher
    steps:
      - attach_workspace:
          at: /tmp/workspace
      - setup_remote_docker
      - run:
          name: Load archived Docker image
          command: docker load -i /tmp/workspace/image.tar
      - run:
          name: Publish Docker image to Docker Hub
          command: |
            echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin
            IMAGE_TAG="0.0.${CIRCLE_BUILD_NUM}"
            docker tag $IMAGE_NAME:latest $DOCKERHUB_USERNAME/$IMAGE_NAME:latest
            docker tag $IMAGE_NAME:latest $DOCKERHUB_USERNAME/$IMAGE_NAME:$IMAGE_TAG
            docker push $DOCKERHUB_USERNAME/$IMAGE_NAME:latest
            docker push $DOCKERHUB_USERNAME/$IMAGE_NAME:$IMAGE_TAG

  publish-tag:
    executor: docker-publisher
    steps:
      - attach_workspace:
          at: /tmp/workspace
      - setup_remote_docker
      - run:
          name: Load archived Docker image
          command: docker load -i /tmp/workspace/image.tar
      - run:
          name: Publish Docker image to Docker Hub
          command: |
            echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin
            IMAGE_TAG="${CIRCLE_TAG#v}"
            docker tag $IMAGE_NAME:latest $DOCKERHUB_USERNAME/$IMAGE_NAME:latest
            docker tag $IMAGE_NAME:latest $DOCKERHUB_USERNAME/$IMAGE_NAME:$IMAGE_TAG
            docker push $DOCKERHUB_USERNAME/$IMAGE_NAME:latest
            docker push $DOCKERHUB_USERNAME/$IMAGE_NAME:$IMAGE_TAG

workflows:
  build-and-publish:
    jobs:
      - build:
          filters: pipeline.git.branch or (pipeline.git.tag matches /^v.*/)
      - publish-latest:
          requires:
            - build
          filters: pipeline.git.branch == "main"
      - publish-tag:
          requires:
            - build
          filters: pipeline.git.tag matches /^v.*/

Conclusion

These versioning techniques are just building blocks. You can make tagging the versions of your image as complex or as simple as you want. You could even use this knowledge to upload an image to your own private registry, instead of Docker Hub, for specific tags.

If we’d rather not maintain these steps ourselves, the circleci/docker orb packages the same login, build, and push sequence into a single publish job.

The repository used while writing this article is available on GitHub: https://github.com/CIRCLECI-GWP/docker-building-on-ci


Jonathan Cardoso is passionate about DevOps, open source, and gaming. He has six years of experience helping companies around the world move their objectives forward with technical solutions. He currently works remotely from Brazil as a Full-Stack Developer and DevOps specialist at HelloMD.