GitHub Action to build and push Docker images with Buildx, designed exclusively for Blacksmith runners. This action leverages Blacksmith's stickydisk primitive to mount Docker layer caches directly into Blacksmith runners, providing out of the box incremental builds.

Important: This action only works with Blacksmith runners. When running, it will:

1. Mount a repository-specific Sticky Disk volume containing Docker layer caches directly into the runner
2. Automatically spin up a local buildkit instance on top of this mounted volume
3. Override any remote builder configuration options to ensure optimal use of the local cache

As a result, any configuration options related to remote builders or builder setup will be ignored.

---

Usage

Note: This action requires a Blacksmith runner. It will not work with standard GitHub runners or other CI environments.

In the examples below we are using these additional actions:

• setup-qemu action can be useful if you want to add emulation support with QEMU to be able to build against more platforms.
• login action will take care to log in against a Docker registry.

Note that unlike the original Docker build-push action, you do not need to set up Buildx separately as this is handled automatically by the Blacksmith runner.

Git context

By default, this action uses the Git context, so you don't need to use the actions/checkout action to check out the repository as this will be done directly by BuildKit.

name: ci

on:
  push:

jobs:
  docker:
    runs-on: blacksmith
    steps:
      -
        name: Set up QEMU
        uses: docker/setup-qemu-action@v3
      -
        name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      -
        name: Build and push
        uses: useblacksmith/build-push-action@v1
        with:
          push: true
          tags: user/app:latest

Path context

name: ci

on:
  push:

jobs:
  docker:
    runs-on: blacksmith
    steps:
      -
        name: Checkout
        uses: actions/checkout@v4
      -
        name: Set up QEMU
        uses: docker/setup-qemu-action@v3
      -
        name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      -
        name: Build and push
        uses: useblacksmith/build-push-action@v1
        with:
          context: .
          push: true
          tags: user/app:latest

Examples

• Multi-platform image
• Secrets
• Push to multi-registries
• Manage tags and labels
• Cache management
• Export to Docker
• Test before push
• Local registry
• Share built image between jobs
• Named contexts
• Copy image between registries
• Update Docker Hub repo description
• SBOM and provenance attestations
• Annotations
• Reproducible builds

Summaries

This action generates a job summary that provides a detailed overview of the build execution. The summary shows an overview of all the steps executed during the build, including the build inputs and eventual errors.

The summary also includes a link for downloading the build record with additional details about the build, including build stats, logs, outputs, and more. The build record can be imported to Docker Desktop for inspecting the build in greater detail.

Summaries are enabled by default, but can be disabled with the DOCKER_BUILD_SUMMARY environment variable.

For more information about summaries, refer to the documentation.

Customizing

inputs

The following inputs can be used as step.with keys:

List type is a newline-delimited string

cache-from: |
  user/app:cache
  type=local,src=path/to/dir

CSV type is a comma-delimited string

tags: name/app:latest,name/app:1.0.0

Name	Type	Description
add-hosts	List/CSV	List of customs host-to-IP mapping (e.g., docker:10.180.0.1)
allow	List/CSV	List of extra privileged entitlement (e.g., network.host,security.insecure)
annotations	List	List of annotation to set to the image
attests	List	List of attestation parameters (e.g., type=sbom,generator=image)
builder	String	Builder instance (see setup-buildx action)
build-args	List	List of build-time variables
build-contexts	List	List of additional build contexts (e.g., name=path)
cache-from	List	List of external cache sources (e.g., type=local,src=path/to/dir)
cache-to	List	List of cache export destinations (e.g., type=local,dest=path/to/dir)
cgroup-parent	String	Optional parent cgroup for the container used in the build
context	String	Build's context is the set of files located in the specified PATH or URL (default Git context)
file	String	Path to the Dockerfile. (default {context}/Dockerfile)
labels	List	List of metadata for an image
load	Bool	Load is a shorthand for --output=type=docker (default false)
network	String	Set the networking mode for the RUN instructions during build
no-cache	Bool	Do not use cache when building the image (default false)
no-cache-filters	List/CSV	Do not cache specified stages
outputs	List	List of output destinations (format: type=local,dest=path)
platforms	List/CSV	List of target platforms for build
provenance	Bool/String	Generate provenance attestation for the build (shorthand for --attest=type=provenance)
pull	Bool	Always attempt to pull all referenced images (default false)
push	Bool	Push is a shorthand for --output=type=registry (default false)
sbom	Bool/String	Generate SBOM attestation for the build (shorthand for --attest=type=sbom)
secrets	List	List of secrets to expose to the build (e.g., key=string, GIT_AUTH_TOKEN=mytoken)
secret-envs	List/CSV	List of secret env vars to expose to the build (e.g., key=envname, MY_SECRET=MY_ENV_VAR)
secret-files	List	List of secret files to expose to the build (e.g., key=filename, MY_SECRET=./secret.txt)
shm-size	String	Size of /dev/shm (e.g., 2g)
ssh	List	List of SSH agent socket or keys to expose to the build
tags	List/CSV	List of tags
target	String	Sets the target stage to build
ulimit	List	Ulimit options (e.g., nofile=1024:1024)
github-token	String	GitHub Token used to authenticate against a repository for Git context (default ${{ github.token }})

outputs

The following outputs are available:

Name	Type	Description
imageid	String	Image ID
digest	String	Image digest
metadata	JSON	Build result metadata

environment variables

Name	Type	Default	Description
DOCKER_BUILD_CHECKS_ANNOTATIONS	Bool	true	If false, GitHub annotations are not generated for build checks
DOCKER_BUILD_SUMMARY	Bool	true	If false, build summary generation is disabled
DOCKER_BUILD_RECORD_UPLOAD	Bool	true	If false, build record upload as GitHub artifact is disabled
DOCKER_BUILD_RECORD_RETENTION_DAYS	Number		Duration after which build record artifact will expire in days. Defaults to repository/org retention settings if unset or 0

Troubleshooting

See TROUBLESHOOTING.md

Contributing

Want to contribute? Awesome! You can find information about contributing to this project in the CONTRIBUTING.md