Try Live
Add Docs
Rankings
Pricing
Docs
Install
Theme
Install
Docs
Pricing
More...
More...
Try Live
Rankings
Enterprise
Create API Key
Add Docs
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
Context
Skills
Chat
Benchmark
Suggestions
Latest
Show doc for...
Code
Info
Show Results
Context Summary (auto-generated)
Raw
Copy
Link
# 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.