GitHub Actions: Docker Build Workflow From Dispatch

Oct 31, 2025 by Admin 52 views

Hey guys! Ever wondered how to automate your Docker builds using GitHub Actions triggered by a dispatch event? Well, you're in the right place! This guide will walk you through setting up a workflow that builds and pushes Docker images when triggered from another repository. We'll cover everything from extracting the version tag to building the image and pushing it to your registry. So, let's dive in and make your Docker workflows super efficient!

Understanding the Goal

Our main goal here is to create a GitHub Actions workflow that can be triggered from another repository, such as MOSuite or SCOT. This setup allows us to centralize our Dockerfile management while keeping the build process automated. The workflow will:

Be triggered by a repository_dispatch event: This means another repository can send a signal to kick off our workflow.
Extract the version tag from the dispatch payload: We'll use this tag to version our Docker images.
Copy the Dockerfile with a version-specific name: This helps us maintain different versions of our Dockerfiles.
Build the Docker image: We'll use the extracted version tag in the image tag.
Push the Docker image to a registry: This ensures our image is ready for deployment.

This approach is super handy because it decouples the Dockerfile definitions from the repositories where they're used. Imagine you have multiple projects using similar Docker configurations. Instead of duplicating the Dockerfile across each project, you can maintain a single source of truth and trigger builds as needed. This not only reduces redundancy but also simplifies updates and maintenance. When you need to make a change to the Docker configuration, you only need to update it in one place, and all dependent projects can pull the updated image.

Setting Up the Workflow

Let's break down the process of setting up the GitHub Actions workflow step by step. First, you'll need to create a new workflow file in your repository under the .github/workflows directory. This file, typically named something like docker-build.yml, will define the steps for our automated build process. We'll start by specifying the trigger for the workflow, which in our case is the repository_dispatch event. This event allows us to trigger the workflow from another repository using a specific event type.

Next, we'll define the jobs that need to be executed as part of the workflow. In our scenario, we'll have a single job that handles the entire Docker build and push process. This job will run on a GitHub-hosted runner, which provides a clean and consistent environment for our builds. Within the job, we'll define a series of steps, each performing a specific task. These steps will include extracting the version tag from the dispatch payload, copying the Dockerfile, building the Docker image, and pushing it to a container registry. Each step will be carefully configured to ensure that the process is smooth and error-free. By breaking the workflow into smaller, manageable steps, we make it easier to troubleshoot and maintain. Additionally, this modular approach allows us to reuse certain steps in other workflows if needed, further enhancing the efficiency of our CI/CD pipeline.

Step 1: Create the Workflow File

In your repository, create a file named .github/workflows/docker-build.yml. This is where we'll define our workflow.

name: Docker Build from Dispatch

on:
 repository_dispatch:
 types: [docker_build]

jobs:
 build:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout code
 uses: actions/checkout@v3

 - name: Extract version tag
 id: extract_version
 run: echo "::set-output name=version::${{ github.event.client_payload.version }}"

 - name: Copy Dockerfile
 run: cp Dockerfile Dockerfile.${{ steps.extract_version.outputs.version }}

 - name: Set up Docker Buildx
 uses: docker/setup-buildx-action@v2

 - name: Login to Docker Hub
 uses: docker/login-action@v2
 with:
 username: $\{{ secrets.DOCKER_USERNAME }}\$
 password: $\{{ secrets.DOCKER_PASSWORD }}\$

 - name: Build and push
 uses: docker/build-push-action@v3
 with:
 context: .
 file: Dockerfile.${{ steps.extract_version.outputs.version }}
 push: true
 tags: |
 your-docker-username/your-image:${{ steps.extract_version.outputs.version }}
 your-docker-username/your-image:latest

Step 2: Understanding the YAML File

Let's break down what's happening in this YAML file:

name: This is the name of our workflow, which will appear in the GitHub Actions UI.
on: This section specifies the trigger for the workflow. We're using repository_dispatch with the type docker_build.
jobs: This defines the jobs that will run in our workflow.
build: This is the name of our job.
runs-on: Specifies the runner environment. We're using ubuntu-latest.
steps: This is a list of steps that will be executed in the job.
- Checkout code: This step checks out the repository code using the actions/checkout@v3 action.
- Extract version tag: This step extracts the version tag from the client_payload of the dispatch event. We use the echo command to set an output variable named version.
- Copy Dockerfile: This step copies the Dockerfile to a new file named Dockerfile.{version_tag}. This is crucial for versioning our Dockerfiles.
- Set up Docker Buildx: This step sets up Docker Buildx, which allows us to build multi-platform images.
- Login to Docker Hub: This step logs in to Docker Hub using the provided secrets.
- Build and push: This step builds and pushes the Docker image using the docker/build-push-action@v3 action. We specify the context, Dockerfile, and tags for the image.

Step 3: Setting Up Secrets

You'll notice that we're using secrets for the Docker Hub username and password (DOCKER_USERNAME and DOCKER_PASSWORD). You need to set these up in your repository settings:

Go to your repository on GitHub.
Click on