Docker Build GitHub Actions
GitHub Actions automates your build, test, and deployment pipeline. Use Docker GitHub Builder to build and publish images with Docker-maintained reusable workflows. GitHub Builder manages Buildx setup, platform distribution, metadata, and signing. Start with GitHub Builder for supported build tasks, and compose individual actions when you need custom job steps or controls outside the reusable workflow interface.
Get started
Build an image from your GitHub repository and push it to Docker Hub with the following workflow.
Prerequisites
- A GitHub repository with your application and a
Dockerfileat its root. - A Docker Hub account and a personal access token with permission to push images.
Configure your GitHub repository
Add your Docker Hub credentials to your GitHub repository:
- Open your repository's Settings.
- Under Security, go to Secrets and variables > Actions.
- Under Secrets, create a repository secret named
DOCKERHUB_TOKENcontaining your Docker access token. - Under Variables, create a repository variable named
DOCKERHUB_USERNAMEcontaining your Docker Hub username.
Set up your GitHub Actions workflow
Create .github/workflows/docker-ci.yml in your repository with the following
contents. Replace my-image with the name of your Docker Hub repository, and
change main if your default branch has a different name.
name: ci
on:
push:
branches:
- main
pull_request:
jobs:
build:
uses: docker/github-builder/.github/workflows/build.yml@v1
permissions:
contents: read
id-token: write
with:
output: image
push: ${{ github.event_name != 'pull_request' }}
set-meta-labels: true
set-meta-annotations: true
meta-images: ${{ vars.DOCKERHUB_USERNAME }}/my-image
secrets:
registry-auths: |
- registry: docker.io
username: ${{ vars.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}Call the reusable workflow with uses at the job level, rather than inside
steps. Grant contents: read to fetch the repository and id-token: write
for signing with GitHub's OpenID Connect token. With the default sign: auto,
GitHub Builder signs attestation manifests when pushing an image. See the
Build workflow for inputs and outputs.
Commit the workflow file and push it to your default branch to run it. The
workflow also runs on pull requests. With push: false, the default
registry-login: auto skips registry login and sign: auto skips signing.
Pull requests from forks can build without Docker Hub secrets or a writable
OpenID Connect token. Builds that need private dependencies still need access
to those dependencies.
GitHub Builder builds from the repository at the triggering Git reference. Files changed in a caller job aren't included in the build.
GitHub Builder uses the metadata action to generate tags from the GitHub event.
For example, a push to main publishes DOCKERHUB_USERNAME/my-image:main.
The set-meta-labels and set-meta-annotations switches also apply generated
labels and annotations; both are disabled by default. See
Manage tags and labels and Annotations
to customize this metadata.
This workflow builds images but doesn't run application tests. To add tests, see Test before push. For additional build options, see Multi-platform images and SBOM and provenance attestations.
Use the Build workflow for Dockerfile inputs, or the Bake workflow for a build defined in Bake. Both support image and local file output. For details on platform distribution and outputs, see GitHub Builder architecture.
Build with individual actions
Use individual actions to load images into a job's Docker image store, run
steps before or after a build on the same runner, or configure the builder
directly. GitHub Builder's image output publishes to a registry; its local output
exports files. Neither loads an image into the caller's Docker image store or
exports a Docker image archive. The following alternative uses the same
credentials, triggers, and metadata as the GitHub Builder example:
name: Build and push Docker image
on:
push:
branches:
- main
pull_request:
permissions:
contents: read
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Extract Docker image metadata
id: meta
uses: docker/metadata-action@v6
with:
images: ${{ vars.DOCKERHUB_USERNAME }}/my-image
- name: Sign in to Docker Hub
if: github.event_name != 'pull_request'
uses: docker/login-action@v4
with:
username: ${{ vars.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v4
- name: Build and push Docker image
uses: docker/build-push-action@v7
with:
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
annotations: ${{ steps.meta.outputs.annotations }}The build action uses Git context by default: BuildKit fetches the repository at the triggering Git reference. No checkout step is needed, and changes made by earlier steps aren't included. Use a checkout and a path context when the build needs files changed by earlier steps.
Available actions
The following GitHub Actions are available:
- Build and push Docker images: build and push Docker images with BuildKit.
- Docker Buildx Bake: enables using high-level builds with Bake.
- Docker Login: sign in to a Docker registry.
- Docker Setup Buildx: creates and boots a BuildKit builder.
- Docker Metadata action: extracts metadata from Git reference and GitHub events to generate tags, labels, and annotations.
- Docker Setup Compose: installs and sets up Compose.
- Docker Setup Docker: installs Docker Engine.
- Docker Setup QEMU: installs QEMU static binaries for multi-platform builds.
- Docker Scout: analyze Docker images for security vulnerabilities.