## About GitHub Action to build and push Docker images. > :bulb: See also our [setup-buildx](https://github.com/docker/setup-buildx-action) > and [setup-qemu](https://github.com/docker/setup-qemu-action) actions ___ * [Usage](#usage) * [Quick start](#quick-start) * [Multi-platform image](#multi-platform-image) * [Git context](#git-context) * [Complete workflow](#complete-workflow) * [Customizing](#customizing) * [inputs](#inputs) * [outputs](#outputs) * [Limitation](#limitation) ## Usage This action uses our [setup-buildx](https://github.com/docker/setup-buildx-action) action that extends the `docker build` command named [buildx](https://github.com/docker/buildx) with the full support of the features provided by [Moby BuildKit](https://github.com/moby/buildkit) builder toolkit. This includes multi-arch build, build-secrets, remote cache, etc. and different builder deployment/namespacing options. ### Quick start ```yaml name: ci on: push: branches: master jobs: main: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v2 - name: Set up QEMU uses: docker/setup-qemu-action@v1 with: platforms: all - name: Set up Docker Buildx id: buildx uses: docker/setup-buildx-action@v1 - name: Login to DockerHub uses: crazy-max/ghaction-docker-login@v1 with: username: ${{ secrets.DOCKER_USERNAME }} password: ${{ secrets.DOCKER_PASSWORD }} - name: Build and push id: docker_build uses: docker/build-push-action@v2 with: builder: ${{ steps.buildx.outputs.name }} push: true tags: user/app:latest - name: Image digest run: echo ${{ steps.docker_build.outputs.digest }} ``` ### Multi-platform image ```yaml name: ci on: push: branches: master jobs: multi: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v2 - name: Set up QEMU uses: docker/setup-qemu-action@v1 with: platforms: all - name: Set up Docker Buildx id: buildx uses: docker/setup-buildx-action@v1 - name: Login to DockerHub uses: crazy-max/ghaction-docker-login@v1 with: username: ${{ secrets.DOCKER_USERNAME }} password: ${{ secrets.DOCKER_PASSWORD }} - name: Build and push uses: docker/build-push-action@v2 with: builder: ${{ steps.buildx.outputs.name }} context: . file: ./Dockerfile platforms: linux/amd64,linux/arm64,linux/386 push: true tags: | user/app:latest user/app:1.0.0 ``` ### Git context You can build from Git directly without [`actions/checkout`](https://github.com/actions/checkout/) action, even in private repositories if your `context` is a valid Git url: ```yaml name: ci on: push: branches: master jobs: git-context: runs-on: ubuntu-latest steps: - name: Set up QEMU uses: docker/setup-qemu-action@v1 with: platforms: all - name: Set up Docker Buildx id: buildx uses: docker/setup-buildx-action@v1 with: version: latest - name: Login to DockerHub uses: crazy-max/ghaction-docker-login@v1 with: username: ${{ secrets.DOCKER_USERNAME }} password: ${{ secrets.DOCKER_PASSWORD }} - name: Build and push uses: docker/build-push-action@v2 with: builder: ${{ steps.buildx.outputs.name }} context: "${{ github.repositoryUrl }}#${{ github.ref }}" platforms: linux/amd64,linux/arm64,linux/386 push: true tags: | name/app:latest name/app:1.0.0 env: GIT_AUTH_TOKEN: ${{ github.token }} ``` ### Complete workflow * On `pull_request` event, Docker image `name/app:edge` is **built**. * On `push` event, Docker image `name/app:edge` is **built** and **pushed** to DockerHub. * On `schedule` event, Docker image `name/app:nightly` is **built** and **pushed** to DockerHub. * On `push tags` event, Docker image `name/app:` and `name/app:latest` is **built** and **pushed** to DockerHub. ```yaml name: ci on: schedule: - cron: '0 10 * * *' # everyday at 10am push: branches: master tags: - 'v*.*.*' pull_request: branches: master jobs: docker: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v2 - name: Prepare id: prep run: | DOCKER_IMAGE=name/app VERSION=edge if [[ $GITHUB_REF == refs/tags/* ]]; then VERSION=${GITHUB_REF#refs/tags/v} fi if [ "${{ github.event_name }}" = "schedule" ]; then VERSION=nightly fi TAGS="${DOCKER_IMAGE}:${VERSION}" if [[ $VERSION =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then TAGS="$TAGS,${DOCKER_IMAGE}:latest" fi echo ::set-output name=tags::${TAGS} - name: Set up QEMU uses: docker/setup-qemu-action@v1 with: platforms: all - name: Set up Docker Buildx id: buildx uses: docker/setup-buildx-action@v1 - name: Login to DockerHub if: github.event_name != 'pull_request' uses: crazy-max/ghaction-docker-login@v1 with: username: ${{ secrets.DOCKER_USERNAME }} password: ${{ secrets.DOCKER_PASSWORD }} - name: Build and push id: docker_build uses: docker/build-push-action@v2 with: builder: ${{ steps.buildx.outputs.name }} context: . file: ./Dockerfile platforms: linux/amd64,linux/arm64,linux/386 push: ${{ github.event_name != 'pull_request' }} tags: ${{ steps.prep.outputs.tags }} ``` ## Customizing ### inputs Following inputs can be used as `step.with` keys | Name | Type | Default | Description | |---------------------|---------|-----------------------------------|------------------------------------| | `builder` | String | | Builder instance (see [setup-buildx](https://github.com/docker/setup-buildx-action) action) | | `context` | String | `.` | Build's context is the set of files located in the specified [`PATH` or `URL`](https://docs.docker.com/engine/reference/commandline/build/) | | `file` | String | `./Dockerfile` | Path to the Dockerfile. | | `build-args` | List | | List of build-time variables | | `labels` | List | | List of metadata for an image | | `tags` | List | | List of tags | | `pull` | Bool | `false` | Always attempt to pull a newer version of the image | | `target` | String | | Sets the target stage to build | | `allow` | List | | List of [extra privileged entitlement](https://github.com/docker/buildx#--allowentitlement) (eg. `network.host,security.insecure`) | | `no-cache` | Bool | `false` | Do not use cache when building the image | | `platforms` | List | | List of [target platforms](https://github.com/docker/buildx#---platformvaluevalue) for build | | `load` | Bool | `false` | [Load](https://github.com/docker/buildx#--load) is a shorthand for `--output=type=docker` | | `push` | Bool | `false` | [Push](https://github.com/docker/buildx#--push) is a shorthand for `--output=type=registry` | | `outputs` | List | | List of [output destinations](https://github.com/docker/buildx#-o---outputpath-typetypekeyvalue) (format: `type=local,dest=path`) | | `cache-from` | List | | List of [external cache sources](https://github.com/docker/buildx#--cache-fromnametypetypekeyvalue) (eg. `user/app:cache`, `type=local,src=path/to/dir`) | | `cache-to` | List | | List of [cache export destinations](https://github.com/docker/buildx#--cache-tonametypetypekeyvalue) (eg. `user/app:cache`, `type=local,dest=path/to/dir`) | > List type can be a comma or newline-delimited string > ```yaml > tags: name/app:latest,name/app:1.0.0 > ``` > ```yaml > tags: | > name/app:latest > name/app:1.0.0 > ``` ### outputs Following outputs are available | Name | Type | Description | |---------------|---------|---------------------------------------| | `digest` | String | Image content-addressable identifier also called a digest | ### environment variables Following environment variables can be used as `step.env` keys | Name | Description | |--------------------------|---------------------------------------| | `GIT_AUTH_HEADER`**¹** | Raw authorization header to authenticate against git repository | | `GIT_AUTH_TOKEN`**¹** | `x-access-token` basic auth to authenticate against git repository | > **¹** Only used if `input.context` is a valid git uri. ## Limitation This action is only available for Linux [virtual environments](https://help.github.com/en/articles/virtual-environments-for-github-actions#supported-virtual-environments-and-hardware-resources).