GitHub - docker/build-push-action: GitHub Action to build and push Docker images with Buildx (original) (raw)

About

GitHub Action to build and push Docker images with Buildxwith full support of the features provided by Moby BuildKitbuilder toolkit. This includes multi-platform build, secrets, remote cache, etc. and different builder deployment/namespacing options.

• Usage
  • Git context
  • Path context
• Examples
• Summaries
• Customizing
  • inputs
  • outputs
  • environment variables
• Troubleshooting
• Contributing

Usage

In the examples below we are also using 3 other actions:

• setup-buildx action will create and boot a builder using by default the docker-container driver. This is not required but recommended using it to be able to build multi-platform images, export cache, etc.
• 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.

Git context

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

The git reference will be based on the event that triggered your workflowand will result in the following context: https://github.com/<owner>/<repo>.git#<ref>.

name: ci

on: push:

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

Be careful because any file mutation in the steps that precede the build step will be ignored, including processing of the .dockerignore file since the context is based on the Git reference. However, you can use thePath context using the context input alongside the actions/checkout action to remove this restriction.

Default Git context can also be provided using the Handlebars templateexpression {{defaultContext}}. Here we can use it to provide a subdirectory to the default Git context:

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

Building from the current repository automatically uses the GitHub Token, so it does not need to be passed. If you want to authenticate against another private repository, you have to use a secretnamed GIT_AUTH_TOKEN to be able to authenticate against it with Buildx:

  -
    name: Build and push
    uses: docker/build-push-action@v6
    with:
      push: true
      tags: user/app:latest
      secrets: |
        GIT_AUTH_TOKEN=${{ secrets.MYTOKEN }}

Path context

name: ci

on: push:

jobs: docker: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Login to Docker Hub uses: docker/login-action@v3 with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - name: Set up QEMU uses: docker/setup-qemu-action@v3 - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - name: Build and push uses: docker/build-push-action@v6 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
• Validating build configuration
• 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 summarythat 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 theDOCKER_BUILD_SUMMARY environment variable.

For more information about summaries, refer to thedocumentation.

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

outputs

The following outputs are available:

environment variables

Troubleshooting

See TROUBLESHOOTING.md

Contributing

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