README.md

    GitHub release GitHub marketplace CI workflow Test workflow Codecov

    About

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

    Screenshot


    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 builder 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/checkout action to check out the repository because this will be done directly by BuildKit.

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

    name: ci
    
    on:
      push:
        branches:
          - 'main'
    
    jobs:
      docker:
        runs-on: ubuntu-latest
        steps:
          -
            name: Set up QEMU
            uses: docker/setup-qemu-action@v2
          -
            name: Set up Docker Buildx
            uses: docker/setup-buildx-action@v2
          -
            name: Login to DockerHub
            uses: docker/login-action@v2
            with:
              username: ${{ secrets.DOCKERHUB_USERNAME }}
              password: ${{ secrets.DOCKERHUB_TOKEN }}
          -
            name: Build and push
            uses: docker/build-push-action@v3
            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 the Path context using the context input alongside the actions/checkout action to remove this restriction.

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

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

    Subdirectory for Git context is not yet available for the buildx docker driver.

    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 secret named GIT_AUTH_TOKEN to be able to authenticate against it with buildx:

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

    Path context

    name: ci
    
    on:
      push:
        branches:
          - 'main'
    
    jobs:
      docker:
        runs-on: ubuntu-latest
        steps:
          -
            name: Checkout
            uses: actions/checkout@v2
          -
            name: Set up QEMU
            uses: docker/setup-qemu-action@v2
          -
            name: Set up Docker Buildx
            uses: docker/setup-buildx-action@v2
          -
            name: Login to DockerHub
            uses: docker/login-action@v2
            with:
              username: ${{ secrets.DOCKERHUB_USERNAME }}
              password: ${{ secrets.DOCKERHUB_TOKEN }}
          -
            name: Build and push
            uses: docker/build-push-action@v3
            with:
              context: .
              push: true
              tags: user/app:latest

    Advanced usage

    Customizing

    inputs

    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
    Name Type Description
    add-hosts List/CSV List of customs host-to-IP mapping (e.g., docker:10.180.0.1)
    allow List/CSV List of extra privileged entitlement (e.g., network.host,security.insecure)
    builder String Builder instance (see setup-buildx action)
    build-args List List of build-time variables
    build-contexts List List of additional build contexts (e.g., name=path)
    cache-from List List of external cache sources (e.g., type=local,src=path/to/dir)
    cache-to List List of cache export destinations (e.g., type=local,dest=path/to/dir)
    cgroup-parent String Optional parent cgroup for the container used in the build
    context String Build's context is the set of files located in the specified PATH or URL (default Git context)
    file String Path to the Dockerfile. (default {context}/Dockerfile)
    labels List List of metadata for an image
    load Bool Load is a shorthand for --output=type=docker (default false)
    network String Set the networking mode for the RUN instructions during build
    no-cache Bool Do not use cache when building the image (default false)
    outputs List List of output destinations (format: type=local,dest=path)
    platforms List/CSV List of target platforms for build
    pull Bool Always attempt to pull all referenced images (default false)
    push Bool Push is a shorthand for --output=type=registry (default false)
    secrets List List of secrets to expose to the build (e.g., key=string, GIT_AUTH_TOKEN=mytoken)
    secret-files List List of secret files to expose to the build (e.g., key=filename, MY_SECRET=./secret.txt)
    shm-size String Size of /dev/shm (e.g., 2g)
    ssh List List of SSH agent socket or keys to expose to the build
    tags List/CSV List of tags
    target String Sets the target stage to build
    ulimit List Ulimit options (e.g., nofile=1024:1024)
    github-token String GitHub Token used to authenticate against a repository for Git context (default ${{ github.token }})

    outputs

    Following outputs are available

    Name Type Description
    imageid String Image ID
    digest String Image digest
    metadata JSON Build result metadata

    Troubleshooting

    See TROUBLESHOOTING.md

    Keep up-to-date with GitHub Dependabot

    Since Dependabot has native GitHub Actions support, to enable it on your GitHub repo all you need to do is add the .github/dependabot.yml file:

    version: 2
    updates:
      # Maintain dependencies for GitHub Actions
      - package-ecosystem: "github-actions"
        directory: "/"
        schedule:
          interval: "daily"

    项目简介

    GitHub Action to build and push Docker images with Buildx

    🚀 Github 镜像仓库 🚀

    源项目地址

    https://github.com/docker/build-push-action

    发行版本 20

    v3.0.0

    全部发行版

    贡献者 26

    全部贡献者

    开发语言

    • TypeScript 91.8 %
    • Dockerfile 6.3 %
    • HCL 1.8 %