* [Keep up-to-date with GitHub Dependabot](#keep-up-to-date-with-github-dependabot)
* [Contributing](#contributing)
## Usage
## Usage
In the examples below we are also using 3 other actions:
In the examples below we are also using 3 other actions:
* [`setup-buildx`](https://github.com/docker/setup-buildx-action) action will create and boot a builder using by
* [`setup-buildx`](https://github.com/docker/setup-buildx-action) action will
default the `docker-container` [builder driver](https://github.com/docker/buildx/blob/master/docs/reference/buildx_create.md#driver).
create and boot a builder using by default the [`docker-container` driver](https://docs.docker.com/build/building/drivers/docker-container/).
This is **not required but recommended** using it to be able to build multi-platform images, export cache, etc.
This is **not required but recommended** using it to be able to build
* [`setup-qemu`](https://github.com/docker/setup-qemu-action) action can be useful if you want
multi-platform images, export cache, etc.
to add emulation support with QEMU to be able to build against more platforms.
* [`setup-qemu`](https://github.com/docker/setup-qemu-action) action can be
* [`login`](https://github.com/docker/login-action) action will take care to log in against a Docker registry.
useful if you want to add emulation support with QEMU to be able to build
against more platforms.
* [`login`](https://github.com/docker/login-action) action will take care to
log in against a Docker registry.
### Git context
### Git context
@ -54,7 +58,7 @@ By default, this action uses the [Git context](https://docs.docker.com/engine/re
so you don't need to use the [`actions/checkout`](https://github.com/actions/checkout/)
so you don't need to use the [`actions/checkout`](https://github.com/actions/checkout/)
action to check out the repository as this will be done directly by [BuildKit](https://github.com/moby/buildkit).
action to check out the repository as this will be done directly by [BuildKit](https://github.com/moby/buildkit).
The git reference will be based on the [event that triggered your workflow](https://docs.github.com/en/actions/reference/events-that-trigger-workflows)
The git reference will be based on the [event that triggered your workflow](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows)
and will result in the following context: `https://github.com/<owner>/<repo>.git#<ref>`.
and will result in the following context: `https://github.com/<owner>/<repo>.git#<ref>`.
```yaml
```yaml
@ -76,7 +80,7 @@ jobs:
name: Set up Docker Buildx
name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
uses: docker/setup-buildx-action@v2
-
-
name: Login to DockerHub
name: Login to DockerHub
uses: docker/login-action@v2
uses: docker/login-action@v2
with:
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
username: ${{ secrets.DOCKERHUB_USERNAME }}
@ -123,10 +127,10 @@ to the default Git context:
> Buildkit 0.8.2 at the moment, it does not support this feature. It's therefore
> Buildkit 0.8.2 at the moment, it does not support this feature. It's therefore
> required to use the `setup-buildx-action` at the moment.
> required to use the `setup-buildx-action` at the moment.
Building from the current repository automatically uses the [GitHub Token](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token),
Building from the current repository automatically uses the [GitHub Token](https://docs.github.com/en/actions/security-guides/automatic-token-authentication),
so it does not need to be passed. If you want to authenticate against another
so it does not need to be passed. If you want to authenticate against another
private repository, you have to use a [secret](docs/advanced/secrets.md) named
private repository, you have to use a [secret](docs/advanced/secrets.md) named
`GIT_AUTH_TOKEN` to be able to authenticate against it with buildx:
`GIT_AUTH_TOKEN` to be able to authenticate against it with Buildx:
```yaml
```yaml
-
-
@ -163,7 +167,7 @@ jobs:
name: Set up Docker Buildx
name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
uses: docker/setup-buildx-action@v2
-
-
name: Login to DockerHub
name: Login to DockerHub
uses: docker/login-action@v2
uses: docker/login-action@v2
with:
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
username: ${{ secrets.DOCKERHUB_USERNAME }}
@ -191,7 +195,7 @@ jobs:
* [Test your image before pushing it](docs/advanced/test-before-push.md)
* [Test your image before pushing it](docs/advanced/test-before-push.md)
| `build-args` | List | List of [build-time variables](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#build-arg) |
| `build-args` | List | List of [build-time variables](https://docs.docker.com/engine/reference/commandline/buildx_build/#build-arg) |
| `build-contexts` | List | List of additional [build contexts](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#build-context) (e.g., `name=path`) |
| `build-contexts` | List | List of additional [build contexts](https://docs.docker.com/engine/reference/commandline/buildx_build/#build-context) (e.g., `name=path`) |
| `cache-from` | List | List of [external cache sources](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#cache-from) (e.g., `type=local,src=path/to/dir`) |
| `cache-from` | List | List of [external cache sources](https://docs.docker.com/engine/reference/commandline/buildx_build/#cache-from) (e.g., `type=local,src=path/to/dir`) |
| `cache-to` | List | List of [cache export destinations](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#cache-to) (e.g., `type=local,dest=path/to/dir`) |
| `cache-to` | List | List of [cache export destinations](https://docs.docker.com/engine/reference/commandline/buildx_build/#cache-to) (e.g., `type=local,dest=path/to/dir`) |
| `cgroup-parent` | String | Optional [parent cgroup](https://docs.docker.com/engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent) for the container used in the build |
| `cgroup-parent` | String | Optional [parent cgroup](https://docs.docker.com/engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent) for the container used in the build |
| `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/) (default [Git context](#git-context)) |
| `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/) (default [Git context](#git-context)) |
| `file` | String | Path to the Dockerfile. (default `{context}/Dockerfile`) |
| `file` | String | Path to the Dockerfile. (default `{context}/Dockerfile`) |
| `labels` | List | List of metadata for an image |
| `labels` | List | List of metadata for an image |
| `load` | Bool | [Load](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#load) is a shorthand for `--output=type=docker` (default `false`) |
| `load` | Bool | [Load](https://docs.docker.com/engine/reference/commandline/buildx_build/#load) is a shorthand for `--output=type=docker` (default `false`) |
| `network` | String | Set the networking mode for the `RUN` instructions during build |
| `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`) |
| `no-cache` | Bool | Do not use cache when building the image (default `false`) |
| `no-cache-filters` | List/CSV | Do not cache specified stages |
| `no-cache-filters` | List/CSV | Do not cache specified stages |
| `outputs`¹ | List | List of [output destinations](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#output) (format: `type=local,dest=path`) |
| `outputs`¹ | List | List of [output destinations](https://docs.docker.com/engine/reference/commandline/buildx_build/#output) (format: `type=local,dest=path`) |
| `platforms` | List/CSV | List of [target platforms](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#platform) for build |
| `platforms` | List/CSV | List of [target platforms](https://docs.docker.com/engine/reference/commandline/buildx_build/#platform) for build |
| `pull` | Bool | Always attempt to pull all referenced images (default `false`) |
| `pull` | Bool | Always attempt to pull all referenced images (default `false`) |
| `push` | Bool | [Push](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#push) is a shorthand for `--output=type=registry` (default `false`) |
| `push` | Bool | [Push](https://docs.docker.com/engine/reference/commandline/buildx_build/#push) is a shorthand for `--output=type=registry` (default `false`) |
| `secrets` | List | List of [secrets](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#secret) to expose to the build (e.g., `key=string`, `GIT_AUTH_TOKEN=mytoken`) |
| `secrets` | List | List of [secrets](https://docs.docker.com/engine/reference/commandline/buildx_build/#secret) to expose to the build (e.g., `key=string`, `GIT_AUTH_TOKEN=mytoken`) |
| `secret-files` | List | List of [secret files](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#secret) to expose to the build (e.g., `key=filename`, `MY_SECRET=./secret.txt`) |
| `secret-files` | List | List of [secret files](https://docs.docker.com/engine/reference/commandline/buildx_build/#secret) to expose to the build (e.g., `key=filename`, `MY_SECRET=./secret.txt`) |
| `ssh` | List | List of [SSH agent socket or keys](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#ssh) to expose to the build |
| `ssh` | List | List of [SSH agent socket or keys](https://docs.docker.com/engine/reference/commandline/buildx_build/#ssh) to expose to the build |
| `tags` | List/CSV | List of tags |
| `tags` | List/CSV | List of tags |
| `target` | String | Sets the target stage to build |
| `target` | String | Sets the target stage to build |
| `ulimit` | List | [Ulimit](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#-set-ulimits---ulimit) options (e.g., `nofile=1024:1024`) |
| `ulimit` | List | [Ulimit](https://docs.docker.com/engine/reference/commandline/buildx_build/#ulimit) options (e.g., `nofile=1024:1024`) |
| `github-token` | String | GitHub Token used to authenticate against a repository for [Git context](#git-context) (default `${{ github.token }}`) |
| `github-token` | String | GitHub Token used to authenticate against a repository for [Git context](#git-context) (default `${{ github.token }}`) |
> **Note**
> **Note**
>
>
@ -249,28 +253,17 @@ Following inputs can be used as `step.with` keys
Since [Dependabot](https://docs.github.com/en/github/administering-a-repository/keeping-your-actions-up-to-date-with-github-dependabot)
Want to contribute? Awesome! You can find information about contributing to
has [native GitHub Actions support](https://docs.github.com/en/github/administering-a-repository/configuration-options-for-dependency-updates#package-ecosystem),
this project in the [CONTRIBUTING.md](/.github/CONTRIBUTING.md)
to enable it on your GitHub repo all you need to do is add the `.github/dependabot.yml` file:
> More info about cache on [BuildKit](https://github.com/moby/buildkit#export-cache) and [Buildx](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#cache-from) repositories.
> **Note**
>
> See [our guide](https://github.com/docker/buildx/blob/master/docs/guides/cache/index.md)
> for more details about cache storage backends.
## Inline cache
## Inline cache
In most cases you want to use the [`type=inline` cache exporter](https://github.com/moby/buildkit#inline-push-image-and-cache-together).
In most cases you want to use the [`type=inline` cache exporter](https://github.com/docker/buildx/blob/master/docs/guides/cache/inline.md).
However, note that the `inline` cache exporter only supports `min` cache mode. To enable `max` cache mode, push the
However, note that the `inline` cache exporter only supports `min` cache mode. To enable `max` cache mode, push the
image and the cache separately by using the `registry` cache exporter as shown in the [next example](#registry-cache).
image and the cache separately by using the `registry` cache exporter as shown in the [next example](#registry-cache).
@ -33,7 +36,7 @@ jobs:
name: Set up Docker Buildx
name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
uses: docker/setup-buildx-action@v2
-
-
name: Login to DockerHub
name: Login to DockerHub
uses: docker/login-action@v2
uses: docker/login-action@v2
with:
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
username: ${{ secrets.DOCKERHUB_USERNAME }}
@ -52,7 +55,7 @@ jobs:
## Registry cache
## Registry cache
You can import/export cache from a cache manifest or (special) image configuration on the registry with the
You can import/export cache from a cache manifest or (special) image configuration on the registry with the
to fetch and upload cache blobs. That's why this type of cache should be exclusively used in a GitHub Action workflow
backend uses the [GitHub Cache API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md)
as the `url` (`$ACTIONS_CACHE_URL`) and `token` (`$ACTIONS_RUNTIME_TOKEN`) attributes are populated when a workflow
to fetch and upload cache blobs. That's why this type of cache should be
exclusively used in a GitHub Action workflow as the `url` (`$ACTIONS_CACHE_URL`)
and `token` (`$ACTIONS_RUNTIME_TOKEN`) attributes are populated when a workflow
is started.
is started.
```yaml
```yaml
@ -123,7 +128,7 @@ jobs:
name: Set up Docker Buildx
name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
uses: docker/setup-buildx-action@v2
-
-
name: Login to DockerHub
name: Login to DockerHub
uses: docker/login-action@v2
uses: docker/login-action@v2
with:
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
username: ${{ secrets.DOCKERHUB_USERNAME }}
@ -141,11 +146,13 @@ jobs:
### Local cache
### Local cache
> :warning: At the moment caches are copied over the existing cache so it [keeps growing](https://github.com/docker/build-push-action/issues/252).
> **Warning**
> The `Move cache` step is used as a temporary fix (see https://github.com/moby/buildkit/issues/1896).
>
> At the moment caches are copied over the existing cache, so it [keeps growing](https://github.com/docker/build-push-action/issues/252).
> The `Move cache` step is used as a workaround (see [moby/buildkit#1896](https://github.com/moby/buildkit/issues/1896) for more info).
You can also leverage [GitHub cache](https://docs.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows)
You can also leverage [GitHub cache](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows)
using [actions/cache](https://github.com/actions/cache) and [`type=local` cache exporter](https://github.com/moby/buildkit#local-directory-1)
using the [actions/cache](https://github.com/actions/cache) and [`type=local` cache exporter](https://github.com/docker/buildx/blob/master/docs/guides/cache/local.md)
You can build multi-platform images using the [`platforms` input](../../README.md#inputs) as described below.
You can build [multi-platform images](https://docs.docker.com/build/building/multi-platform/)
using the [`platforms` input](../../README.md#inputs) as described below.
> :bulb: List of available platforms will be displayed and available through our [setup-buildx](https://github.com/docker/setup-buildx-action#about) action.
> **Note**
>
> :bulb: If you want support for more platforms, you can use QEMU with our [setup-qemu](https://github.com/docker/setup-qemu-action) action.
> * List of available platforms will be displayed and available through our
In the following example we will expose and use the [GITHUB_TOKEN secret](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret)
In the following example we will expose and use the [GITHUB_TOKEN secret](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret)
as provided by GitHub in your workflow.
as provided by GitHub in your workflow.
First let's create our `Dockerfile` to use our secret:
First let's create our `Dockerfile` to use our secret:
```Dockerfile
```dockerfile
#syntax=docker/dockerfile:1.2
# syntax=docker/dockerfile:1
FROM alpine
FROM alpine
RUN --mount=type=secret,id=github_token \
RUN --mount=type=secret,id=github_token \
cat /run/secrets/github_token
cat /run/secrets/github_token
```
```
As you can see we have named our secret `github_token`. Here is the workflow you can use to expose this secret using
As you can see we have named our secret `github_token`. Here is the workflow
the [`secrets` input](../../README.md#inputs):
you can use to expose this secret using the [`secrets` input](../../README.md#inputs):
```yaml
```yaml
name: ci
name: ci
@ -48,14 +47,17 @@ jobs:
"github_token=${{ secrets.GITHUB_TOKEN }}"
"github_token=${{ secrets.GITHUB_TOKEN }}"
```
```
> :bulb: You can also expose a secret file to the build with [`secret-files`](../../README.md#inputs) input:
> **Note**
>
> You can also expose a secret file to the build with the [`secret-files`](../../README.md#inputs) input:
> ```yaml
> ```yaml
> secret-files: |
> secret-files: |
> "MY_SECRET=./secret.txt"
> "MY_SECRET=./secret.txt"
> ```
> ```
If you're using [GitHub secrets](https://docs.github.com/en/actions/reference/encrypted-secrets) and need to handle
If you're using [GitHub secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
multi-line value, you will need to place the key-value pair between quotes:
and need to handle multi-line value, you will need to place the key-value pair
As each job is isolated in its own runner you cannot use your built image between jobs (except for [self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners)).
As each job is isolated in its own runner you cannot use your built image
However, you can [pass data between jobs in a workflow](https://docs.github.com/en/actions/guides/storing-workflow-data-as-artifacts#passing-data-between-jobs-in-a-workflow)
between jobs (except for [self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners)).
using the [actions/upload-artifact](https://github.com/actions/upload-artifact) and [actions/download-artifact](https://github.com/actions/download-artifact)
However, you can [pass data between jobs in a workflow](https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts#passing-data-between-jobs-in-a-workflow)
using the [actions/upload-artifact](https://github.com/actions/upload-artifact)
and [actions/download-artifact](https://github.com/actions/download-artifact)
If you want an "automatic" tag management and [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/master/annotations.md)
If you want an "automatic" tag management and [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/master/annotations.md)
for labels, you can do it in a dedicated step. The following workflow will use the [Docker metadata action](https://github.com/docker/metadata-action)
for labels, you can do it in a dedicated step. The following workflow will use
to handle tags and labels based on GitHub actions events and Git metadata.
the [Docker metadata action](https://github.com/docker/metadata-action) to
handle tags and labels based on GitHub actions events and Git metadata:
CrazyMax
3 years ago