Docker Build Push Action (docker/build-push-action)

Docker Build Push Action

https://github.com/docker/build-push-action
Admin
A GitHub Action to build and push Docker images using Buildx with full support for BuildKit features...

Tokens:7,931
Snippets:65
Trust Score:9.9
Update:22 hours ago
Show doc for...
Context Summary (auto-generated)
Raw
# Docker Build and Push Action

Docker Build Push Action is a GitHub Action that builds and pushes Docker images using Docker Buildx with full support for Moby BuildKit features. It enables multi-platform builds, secrets management, remote caching, attestations (SBOM and provenance), and various builder deployment options directly within GitHub Actions workflows.

The action integrates seamlessly with other Docker GitHub Actions including `setup-buildx-action` for configuring builders, `setup-qemu-action` for multi-platform emulation, and `login-action` for registry authentication. It supports both Git context (building directly from repository without checkout) and path context (building from checked-out files), with automatic GitHub Token handling for private repository access.

## Basic Build and Push with Git Context

Build and push a Docker image directly from the Git repository without needing to checkout files first. BuildKit fetches the repository context automatically.

```yaml
name: ci

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4

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

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
```

## Build with Path Context

Build from a checked-out repository when you need to process files before building or use a custom `.dockerignore`.

```yaml
name: ci

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Login to Docker Hub
        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
        uses: docker/build-push-action@v7
        with:
          context: .
          push: true
          tags: user/app:latest
```

## Multi-Platform Build

Build images for multiple architectures simultaneously using QEMU emulation.

```yaml
name: multi-platform

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4

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

      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          platforms: linux/amd64,linux/arm64,linux/arm/v7
          push: true
          tags: user/app:latest
```

## Build with Build Arguments and Labels

Pass build-time variables and add metadata labels to your image.

```yaml
name: build-with-args

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:${{ github.sha }}
          build-args: |
            VERSION=${{ github.sha }}
            BUILD_DATE=${{ github.event.head_commit.timestamp }}
            NODE_ENV=production
          labels: |
            org.opencontainers.image.title=MyApp
            org.opencontainers.image.description=My application description
            org.opencontainers.image.version=${{ github.sha }}
            org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
```

## Build with Secrets

Securely pass secrets to the build process without embedding them in the image layers.

```yaml
name: build-with-secrets

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          secrets: |
            GIT_AUTH_TOKEN=${{ secrets.MYTOKEN }}
            NPM_TOKEN=${{ secrets.NPM_TOKEN }}
          secret-files: |
            aws_credentials=${{ github.workspace }}/aws-credentials
          secret-envs: |
            MY_SECRET=MY_ENV_VAR
```

## Build with Cache

Use GitHub Actions cache or registry cache to speed up builds.

```yaml
name: build-with-cache

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          cache-from: type=registry,ref=user/app:buildcache
          cache-to: type=registry,ref=user/app:buildcache,mode=max
```

## Build with GitHub Actions Cache Backend

Use the GitHub Actions cache as a build cache backend.

```yaml
name: build-gha-cache

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max
```

## Build with SBOM and Provenance Attestations

Generate Software Bill of Materials (SBOM) and provenance attestations for supply chain security.

```yaml
name: build-with-attestations

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          sbom: true
          provenance: mode=max
```

## Build with Custom Attestations

Configure custom attestation parameters for advanced use cases.

```yaml
name: build-custom-attestations

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          attests: |
            type=sbom,generator=docker/scout-sbom-indexer:latest
            type=provenance,mode=max
```

## Build with Multiple Tags and Registries

Push the same image to multiple registries with different tags.

```yaml
name: multi-registry

on:
  push:
    branches:
      - main
    tags:
      - 'v*'

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Login to GHCR
        uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: |
            user/app:latest
            user/app:${{ github.sha }}
            ghcr.io/${{ github.repository }}:latest
            ghcr.io/${{ github.repository }}:${{ github.sha }}
```

## Build with Custom Dockerfile and Target

Specify a custom Dockerfile path and build target stage.

```yaml
name: build-custom-dockerfile

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

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

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          context: .
          file: ./docker/Dockerfile.production
          target: production
          push: true
          tags: user/app:latest
```

## Build from Subdirectory

Build from a subdirectory of the repository using the default Git context.

```yaml
name: build-subdirectory

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          context: "{{defaultContext}}:mysubdir"
          push: true
          tags: user/app:latest
```

## Build with Named Contexts

Use additional build contexts to include files from other sources.

```yaml
name: build-named-contexts

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

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

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          context: .
          push: true
          tags: user/app:latest
          build-contexts: |
            alpine=docker-image://alpine:3.19
            config=./config
```

## Load Image to Local Docker

Build and load the image into the local Docker daemon for testing before pushing.

```yaml
name: build-and-test

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build for testing
        uses: docker/build-push-action@v7
        with:
          load: true
          tags: user/app:test

      - name: Test image
        run: |
          docker run --rm user/app:test --version
          docker run --rm user/app:test npm test

      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
```

## Build with Custom Outputs

Export build results to local filesystem or other destinations.

```yaml
name: build-export

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and export to tar
        uses: docker/build-push-action@v7
        with:
          tags: user/app:latest
          outputs: type=docker,dest=/tmp/myimage.tar

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: myimage
          path: /tmp/myimage.tar
```

## Build with Annotations

Add OCI annotations to the image manifest.

```yaml
name: build-with-annotations

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          annotations: |
            index:org.opencontainers.image.title=MyApp
            index:org.opencontainers.image.description=Application description
            manifest:org.opencontainers.image.authors=Team Name
```

## Build with Network Configuration

Configure network settings for the build process.

```yaml
name: build-with-network

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          network: host
          add-hosts: |
            docker:10.180.0.1
            api.internal:192.168.1.100
```

## Build with Resource Limits

Configure ulimits and shared memory size for the build.

```yaml
name: build-with-limits

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          shm-size: 2g
          ulimit: |
            nofile=1024:1024
            nproc=3
```

## Build Validation with Call Check

Validate Dockerfile best practices using the check command.

```yaml
name: validate-dockerfile

on:
  pull_request:
    branches:
      - main

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

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

      - name: Validate Dockerfile
        uses: docker/build-push-action@v7
        with:
          context: .
          call: check
```

## Using Action Outputs

Access build outputs including image ID, digest, and metadata for downstream steps.

```yaml
name: build-with-outputs

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        id: build
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest

      - name: Print outputs
        run: |
          echo "Image ID: ${{ steps.build.outputs.imageid }}"
          echo "Digest: ${{ steps.build.outputs.digest }}"
          echo "Metadata: ${{ steps.build.outputs.metadata }}"
```

## Controlling Build Summary and Records

Configure environment variables to control build summary generation and artifact uploads.

```yaml
name: build-custom-summary

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        env:
          DOCKER_BUILD_SUMMARY: true
          DOCKER_BUILD_RECORD_UPLOAD: true
          DOCKER_BUILD_RECORD_RETENTION_DAYS: 7
          DOCKER_BUILD_CHECKS_ANNOTATIONS: true
        with:
          push: true
          tags: user/app:latest
```

## Summary

Docker Build Push Action is the standard solution for building and pushing Docker images in GitHub Actions workflows. Its primary use cases include CI/CD pipelines for containerized applications, multi-architecture image builds for cross-platform support, and secure image publishing with attestations for supply chain security. The action handles complex scenarios like caching strategies, secret management, and registry authentication while providing detailed build summaries and annotations.

Integration patterns typically involve combining this action with `setup-buildx-action` for builder configuration, `login-action` for registry authentication, and `metadata-action` for generating standardized tags and labels. The action supports both simple single-platform builds and advanced multi-platform, multi-registry deployments with comprehensive caching and attestation support. Its outputs (image ID, digest, metadata) enable downstream automation such as deployment triggers, security scanning, and artifact tracking.