Share feedback
Answers are generated based on the documentation.

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 Dockerfile at 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:

  1. Open your repository's Settings.
  2. Under Security, go to Secrets and variables > Actions.
  3. Under Secrets, create a repository secret named DOCKERHUB_TOKEN containing your Docker access token.
  4. Under Variables, create a repository variable named DOCKERHUB_USERNAME containing 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: