Building Docker images with Buildkit in Dispatch

Building Docker images with Buildkit in Dispatch

Buildkit is a cache-efficient, distributed build system for Docker images made by Moby. It is the standard builder used in the Docker daemon, however, it can also be deployed as a service. This tutorial covers how to use the bundled Buildkit instance with Dispatch.


  • Basic knowledge of git, bash, and Docker.
  • A GitHub account.
  • Owner permissions for a project hosted on GitHub or access to create one.
  • A Git repository containing a Dockerfile.
  • Deploy access to a namespace in Kubernetes cluster.
  • Dispatch CLI installed in the environment.

Install Dispatch

See Dispatch Installation for details.

Note When installing Dispatch, be sure to enable the buildkit.enabled flag to enable Buildkit.

Setup repository in Dispatch

See Setting up a Repository in Dispatch for details.

Add your repository to the Dispatch instance:

dispatch ci repository create --service-account=team-1

Add a Dispatchfile to git repository

This tutorial uses starlark to create a file named Dispatchfile that holds the build specification. This is a step-by-step walk-through of creating the Dispatchfile:

  1. Declare the DSL (Domain Specific Language) syntax for our Dispatchfile using shebang:


    This specifies to use version 0.5 of starlark DSL parser.

  2. Dispatch Catalog holds syntactic sugar for reusing various starlark functions that makes your Dispatchfile smaller and allows you focus on actual testing aspects.

  3. Next, import the following helpers:

    1. gitResource: to declare the git repository as a resource that can be sent as input to tasks
    2. pullRequest: to declare a condition to trigger the builds whenever a pull request is updated
    3. buildkit: to build and publish the Docker image
    # Import the gitResource, pullRequest, and kaniko helpers from dispatch catalog
    load("", "gitResource", "pullRequest")
    load("", "buildkit")
  4. Declare the git resource:

    git = gitResource("helloworld-git")

    Any valid kubernetes resource name can be chosen here.

  5. Declare a task to build and push the Docker image using buildkit:

    # Build and push the docker image
    simple_docker = buildkit("build", git, "$YOURDOCKERUSERNAME/helloworld")
  6. Define an Action to run the task on every pull request:

    action(tasks=["build"], on=pullRequest())

The entire Dispatchfile looks like the following:


# vi:syntax=python

load("", "gitResource", "pullRequest")
load("", "buildkit")

git = gitResource("helloworld-git")

# Build and push the docker image
simple_docker = buildkit("build", git, "$YOURDOCKERUSERNAME/helloworld")

simpleTasks = ["unit-test-simple"]
action(tasks=simpleTasks, on=pullRequest())

See full reference of a Dispatchfile. After you commit and push the Dispatchfile and then create a pull request to your repository, the image will build.