actions/docker-build-push
1
0
Fork 0
mirror of https://github.com/docker/build-push-action.git synced 2024-11-15 18:23:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #700 from crazy-max/update-docs

Browse Source 
docs: update links and layout
This commit is contained in:
CrazyMax 2022-10-11 12:07:35 +02:00 committed by GitHub
commit f97d6e2850
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
26 changed files with 196 additions and 168 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
.github/workflows/ci.yml vendored
View File

@ -302,6 +302,29 @@ jobs:
run: | run: |
docker image inspect myimage:latest docker image inspect myimage:latest
secret:
runs-on: ubuntu-latest
steps:
-
name: Checkout
uses: actions/checkout@v3
-
name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
with:
version: ${{ inputs.buildx-version || env.BUILDX_VERSION }}
driver-opts: |
image=${{ inputs.buildkit-image || env.BUILDKIT_IMAGE }}
-
name: Build
uses: ./
with:
context: .
file: ./test/secret.Dockerfile
secrets: |
MYSECRET=foo
INVALID_SECRET=
network: network:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:

123
README.md
View File

@ -6,9 +6,10 @@
## About ## About
GitHub Action to build and push Docker images with [Buildx](https://github.com/docker/buildx) with full support of the GitHub Action to build and push Docker images with [Buildx](https://github.com/docker/buildx)
features provided by [Moby BuildKit](https://github.com/moby/buildkit) builder toolkit. This includes multi-platform with full support of the features provided by [Moby BuildKit](https://github.com/moby/buildkit)
build, secrets, remote cache, etc. and different builder deployment/namespacing options. builder toolkit. This includes multi-platform build, secrets, remote cache, etc.
and different builder deployment/namespacing options.
![Screenshot](.github/build-push-action.png) ![Screenshot](.github/build-push-action.png)
@ -30,23 +31,26 @@ ___
* [Test your image before pushing it](docs/advanced/test-before-push.md) * [Test your image before pushing it](docs/advanced/test-before-push.md)
* [Named contexts](docs/advanced/named-contexts.md) * [Named contexts](docs/advanced/named-contexts.md)
* [Handle tags and labels](docs/advanced/tags-labels.md) * [Handle tags and labels](docs/advanced/tags-labels.md)
* [Update DockerHub repo description](docs/advanced/dockerhub-desc.md) * [Update Docker Hub repo description](docs/advanced/dockerhub-desc.md)
* [Customizing](#customizing) * [Customizing](#customizing)
* [inputs](#inputs) * [inputs](#inputs)
* [outputs](#outputs) * [outputs](#outputs)
* [Troubleshooting](#troubleshooting) * [Troubleshooting](#troubleshooting)
* [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 Docker Hub
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 Docker Hub
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)
* [Named contexts](docs/advanced/named-contexts.md) * [Named contexts](docs/advanced/named-contexts.md)
* [Handle tags and labels](docs/advanced/tags-labels.md) * [Handle tags and labels](docs/advanced/tags-labels.md)
* [Update DockerHub repo description](docs/advanced/dockerhub-desc.md) * [Update Docker Hub repo description](docs/advanced/dockerhub-desc.md)
## Customizing ## Customizing
@ -211,35 +215,35 @@ Following inputs can be used as `step.with` keys
> tags: name/app:latest,name/app:1.0.0 > tags: name/app:latest,name/app:1.0.0
> ``` > ```
| Name | Type | Description | | Name | Type | Description |
|--------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |--------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `add-hosts` | List/CSV | List of [customs host-to-IP mapping](https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host) (e.g., `docker:10.180.0.1`) | | `add-hosts` | List/CSV | List of [customs host-to-IP mapping](https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host) (e.g., `docker:10.180.0.1`) |
| `allow` | List/CSV | List of [extra privileged entitlement](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#allow) (e.g., `network.host,security.insecure`) | | `allow` | List/CSV | List of [extra privileged entitlement](https://docs.docker.com/engine/reference/commandline/buildx_build/#allow) (e.g., `network.host,security.insecure`) |
| `builder` | String | Builder instance (see [setup-buildx](https://github.com/docker/setup-buildx-action) action) | | `builder` | String | Builder instance (see [setup-buildx](https://github.com/docker/setup-buildx-action) action) |
| `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`) |
| `shm-size` | String | Size of [`/dev/shm`](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#-size-of-devshm---shm-size) (e.g., `2g`) | | `shm-size` | String | Size of [`/dev/shm`](https://docs.docker.com/engine/reference/commandline/buildx_build/#shm-size) (e.g., `2g`) |
| `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
Following outputs are available Following outputs are available
| Name | Type | Description | | Name | Type | Description |
|------------|---------|-----------------------------------------| |------------|---------|-----------------------|
| `imageid` | String | Image ID | | `imageid` | String | Image ID |
| `digest` | String | Image digest | | `digest` | String | Image digest |
| `metadata` | JSON | Build result metadata | | `metadata` | JSON | Build result metadata |
## Troubleshooting ## Troubleshooting
See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) See [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
## Keep up-to-date with GitHub Dependabot ## Contributing
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:
```yaml
version: 2
updates:
# Maintain dependencies for GitHub Actions
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "daily"
```

4
TROUBLESHOOTING.md
View File

@ -16,7 +16,7 @@ While pushing to a registry, you may encounter these kinds of issues:
* `unexpected response: 401 Unauthorized` * `unexpected response: 401 Unauthorized`
These issues are not directly related to this action but are rather linked to These issues are not directly related to this action but are rather linked to
[buildx](https://github.com/docker/buildx), [buildkit](https://github.com/moby/buildkit), [Buildx](https://github.com/docker/buildx), [BuildKit](https://github.com/moby/buildkit),
[containerd](https://github.com/containerd/containerd) or the registry on which [containerd](https://github.com/containerd/containerd) or the registry on which
you're pushing your image. The quality of error message depends on the registry you're pushing your image. The quality of error message depends on the registry
and are usually not very informative. and are usually not very informative.
@ -29,7 +29,7 @@ action step and attach BuildKit container logs to your issue.
### With containerd ### With containerd
Next you can test pushing with [containerd action](https://github.com/crazy-max/ghaction-setup-containerd) Next you can test pushing with [containerd action](https://github.com/crazy-max/ghaction-setup-containerd)
using the following workflow. If it works then open an issue on [buildkit](https://github.com/moby/buildkit) using the following workflow. If it works then open an issue on [BuildKit](https://github.com/moby/buildkit)
repository. repository.
```yaml ```yaml

3
__tests__/buildx.test.ts
View File

@ -137,8 +137,7 @@ describe('getSecret', () => {
} }
expect(true).toBe(!invalid); expect(true).toBe(!invalid);
expect(secret).toEqual(`id=${exKey},src=${tmpNameSync}`); expect(secret).toEqual(`id=${exKey},src=${tmpNameSync}`);
const secretValue = await fs.readFileSync(tmpNameSync, 'utf-8'); expect(fs.readFileSync(tmpNameSync, 'utf-8')).toEqual(exValue);
expect(secretValue).toEqual(exValue);
} catch (err) { } catch (err) {
// eslint-disable-next-line jest/no-conditional-expect // eslint-disable-next-line jest/no-conditional-expect
expect(true).toBe(invalid); expect(true).toBe(invalid);

2
dev.Dockerfile
View File

@ -1,4 +1,4 @@
# syntax=docker/dockerfile:1.4 # syntax=docker/dockerfile:1
ARG NODE_VERSION=16 ARG NODE_VERSION=16
ARG DOCKER_VERSION=20.10.13 ARG DOCKER_VERSION=20.10.13

45
docs/advanced/cache.md
View File

@ -6,11 +6,14 @@
* [Cache backend API](#cache-backend-api) * [Cache backend API](#cache-backend-api)
* [Local cache](#local-cache) * [Local cache](#local-cache)
> 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 Docker Hub
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
[`type=registry` cache exporter](https://github.com/moby/buildkit/tree/master#registry-push-image-and-cache-separately). [`type=registry` cache exporter](https://github.com/docker/buildx/blob/master/docs/guides/cache/registry.md).
```yaml ```yaml
name: ci name: ci
@ -73,7 +76,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 Docker Hub
uses: docker/login-action@v2 uses: docker/login-action@v2
with: with:
username: ${{ secrets.DOCKERHUB_USERNAME }} username: ${{ secrets.DOCKERHUB_USERNAME }}
@ -93,15 +96,17 @@ jobs:
### Cache backend API ### Cache backend API
> :test_tube: This cache exporter is considered EXPERIMENTAL until further notice. Please provide feedback on > **Warning**
> [BuildKit repository](https://github.com/moby/buildkit) if you encounter any issues. >
> This cache exporter is considered EXPERIMENTAL until further notice. Please
> provide feedback on [BuildKit repository](https://github.com/moby/buildkit)
> if you encounter any issues.
Since [buildx 0.6.0](https://github.com/docker/buildx/releases/tag/v0.6.0) and [BuildKit 0.9.0](https://github.com/moby/buildkit/releases/tag/v0.9.0), [GitHub Actions cache exporter](https://github.com/docker/buildx/blob/master/docs/guides/cache/gha.md)
you can use the [`type=gha` cache exporter](https://github.com/moby/buildkit/tree/master#github-actions-cache-experimental). backend uses the [GitHub Cache API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md)
to fetch and upload cache blobs. That's why this type of cache should be
GitHub Actions cache exporter backend uses the [GitHub Cache API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md) exclusively used in a GitHub Action workflow as the `url` (`$ACTIONS_CACHE_URL`)
to fetch and upload cache blobs. That's why this type of cache should be exclusively used in a GitHub Action workflow and `token` (`$ACTIONS_RUNTIME_TOKEN`) attributes are populated when a 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 Docker Hub
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)
with this action: with this action:
```yaml ```yaml
@ -175,7 +182,7 @@ jobs:
restore-keys: | restore-keys: |
${{ runner.os }}-buildx- ${{ runner.os }}-buildx-
- -
name: Login to DockerHub name: Login to Docker Hub
uses: docker/login-action@v2 uses: docker/login-action@v2
with: with:
username: ${{ secrets.DOCKERHUB_USERNAME }} username: ${{ secrets.DOCKERHUB_USERNAME }}

43
docs/advanced/copy-between-registries.md
View File

@ -1,10 +1,8 @@
# Copy images between registries # Copy images between registries
Multi-platform images built using buildx can be copied from one registry to another without [Multi-platform images](https://docs.docker.com/build/building/multi-platform/)
changing the image SHA using the [tag-push-action](https://github.com/akhilerm/tag-push-action). built using Buildx can be copied from one registry to another using the
[`imagetools create` command](https://docs.docker.com/engine/reference/commandline/buildx_imagetools_create/):
The following workflow will first push the image to dockerhub, run some tests using the images
and then push to quay and ghcr
```yaml ```yaml
name: ci name: ci
@ -27,13 +25,12 @@ jobs:
- -
name: Set up Docker Buildx name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2 uses: docker/setup-buildx-action@v2
- # quay and ghcr logins for pushing image after testing -
name: Login to Quay Registry name: Login to Docker Hub
uses: docker/login-action@v2 uses: docker/login-action@v2
with: with:
registry: quay.io username: ${{ secrets.DOCKERHUB_USERNAME }}
username: ${{ secrets.QUAY_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }}
password: ${{ secrets.QUAY_TOKEN }}
- -
name: Login to GitHub Container Registry name: Login to GitHub Container Registry
uses: docker/login-action@v2 uses: docker/login-action@v2
@ -41,12 +38,6 @@ jobs:
registry: ghcr.io registry: ghcr.io
username: ${{ github.repository_owner }} username: ${{ github.repository_owner }}
password: ${{ secrets.GITHUB_TOKEN }} password: ${{ secrets.GITHUB_TOKEN }}
-
name: Login to DockerHub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- -
name: Build and push name: Build and push
uses: docker/build-push-action@v3 uses: docker/build-push-action@v3
@ -57,17 +48,11 @@ jobs:
tags: | tags: |
user/app:latest user/app:latest
user/app:1.0.0 user/app:1.0.0
- # run tests using image from docker hub -
name: Run Tests name: Push image to GHCR
run: make tests run: |
- # copy multiplatform image from dockerhub to quay and ghcr docker buildx imagetools create \
name: Push Image to multiple registries --tag ghcr.io/user/app:latest \
uses: akhilerm/tag-push-action@v2.0.0 --tag ghcr.io/user/app:1.0.0 \
with: user/app:latest
src: docker.io/user/app:1.0.0
dst: |
quay.io/user/app:latest
quay.io/user/app:1.0.0
ghcr.io/user/app:latest
ghcr.io/user/app:1.0.0
``` ```

8
docs/advanced/dockerhub-desc.md
View File

@ -1,7 +1,7 @@
# Update DockerHub repo description # Update Docker Hub repo description
You can update the [DockerHub repository description](https://docs.docker.com/docker-hub/repos/) using You can update the [Docker Hub repository description](https://docs.docker.com/docker-hub/repos/)
a third party action called [DockerHub Description](https://github.com/peter-evans/dockerhub-description) using a third party action called [Docker Hub Description](https://github.com/peter-evans/dockerhub-description)
with this action: with this action:
```yaml ```yaml
@ -26,7 +26,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 Docker Hub
uses: docker/login-action@v2 uses: docker/login-action@v2
with: with:
username: ${{ secrets.DOCKERHUB_USERNAME }} username: ${{ secrets.DOCKERHUB_USERNAME }}

3
docs/advanced/local-registry.md
View File

@ -1,6 +1,7 @@
# Local registry # Local registry
For testing purposes you may need to create a [local registry](https://hub.docker.com/_/registry) to push images into: For testing purposes you may need to create a [local registry](https://hub.docker.com/_/registry)
to push images into:
```yaml ```yaml
name: ci name: ci

14
docs/advanced/multi-platform.md
View File

@ -1,10 +1,14 @@
# Multi-platform image # Multi-platform image
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
> [setup-buildx](https://github.com/docker/setup-buildx-action#about) action.
> * If you want support for more platforms, you can use QEMU with our
> [setup-qemu](https://github.com/docker/setup-qemu-action) action.
```yaml ```yaml
name: ci name: ci
@ -28,7 +32,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 Docker Hub
uses: docker/login-action@v2 uses: docker/login-action@v2
with: with:
username: ${{ secrets.DOCKERHUB_USERNAME }} username: ${{ secrets.DOCKERHUB_USERNAME }}

3
docs/advanced/named-contexts.md
View File

@ -7,6 +7,9 @@ Dockerfile defines a stage with the same name it is overwritten.
This can be useful with GitHub Actions to reuse results from other builds or This can be useful with GitHub Actions to reuse results from other builds or
pin an image to a spcific tag in your workflow. pin an image to a spcific tag in your workflow.
* [Pin image to a specific tag](#pin-image-to-a-specific-tag)
* [Usage of the built image in other build steps](#usage-of-the-built-image-in-other-build-steps)
## Pin image to a specific tag ## Pin image to a specific tag
Replace `alpine:latest` with a pinned one: Replace `alpine:latest` with a pinned one:

12
docs/advanced/push-multi-registries.md
View File

@ -1,12 +1,8 @@
# Push to multi-registries # Push to multi-registries
* [Docker Hub and GHCR](#docker-hub-and-ghcr) The following workflow will connect you to [Docker Hub](https://github.com/docker/login-action#dockerhub)
and [GitHub Container Registry](https://github.com/docker/login-action#github-container-registry)
## Docker Hub and GHCR and push the image to these registries:
The following workflow will connect you to [DockerHub](https://github.com/docker/login-action#dockerhub)
and [GitHub Container Registry](https://github.com/docker/login-action#github-container-registry) and push the
image to these registries.
```yaml ```yaml
name: ci name: ci
@ -30,7 +26,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 Docker Hub
uses: docker/login-action@v2 uses: docker/login-action@v2
with: with:
username: ${{ secrets.DOCKERHUB_USERNAME }} username: ${{ secrets.DOCKERHUB_USERNAME }}

38
docs/advanced/secrets.md
View File

@ -1,20 +1,19 @@
# Secrets # Secrets
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
between quotes:
```yaml ```yaml
secrets: | secrets: |
@ -72,13 +74,15 @@ secrets: |
"JSON_SECRET={""key1"":""value1"",""key2"":""value2""}" "JSON_SECRET={""key1"":""value1"",""key2"":""value2""}"
``` ```
| Key | Value | | Key | Value |
|--------------------|--------------------------------------------------| |--------------------|-------------------------------------|
| `MYSECRET` | `***********************` | | `MYSECRET` | `***********************` |
| `GIT_AUTH_TOKEN` | `abcdefghi,jklmno=0123456789` | | `GIT_AUTH_TOKEN` | `abcdefghi,jklmno=0123456789` |
| `MYSECRET` | `aaaaaaaa\nbbbbbbb\nccccccccc` | | `MYSECRET` | `aaaaaaaa\nbbbbbbb\nccccccccc` |
| `FOO` | `bar` | | `FOO` | `bar` |
| `EMPTYLINE` | `aaaa\n\nbbbb\nccc` | | `EMPTYLINE` | `aaaa\n\nbbbb\nccc` |
| `JSON_SECRET` | `{"key1":"value1","key2":"value2"}` | | `JSON_SECRET` | `{"key1":"value1","key2":"value2"}` |
> :bulb: All quote signs need to be doubled for escaping. > **Note**
>
> All quote signs need to be doubled for escaping.

8
docs/advanced/share-image-jobs.md
View File

@ -1,8 +1,10 @@
# Share built image between jobs # Share built image between jobs
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)
actions: actions:
```yaml ```yaml

7
docs/advanced/tags-labels.md
View File

@ -1,8 +1,9 @@
# Handle tags and labels # Handle tags and labels
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:
```yaml ```yaml
name: ci name: ci
@ -51,7 +52,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 Docker Hub
if: github.event_name != 'pull_request' if: github.event_name != 'pull_request'
uses: docker/login-action@v2 uses: docker/login-action@v2
with: with:

10
docs/advanced/test-before-push.md
View File

@ -33,7 +33,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 Docker Hub
uses: docker/login-action@v2 uses: docker/login-action@v2
with: with:
username: ${{ secrets.DOCKERHUB_USERNAME }} username: ${{ secrets.DOCKERHUB_USERNAME }}
@ -59,6 +59,8 @@ jobs:
tags: ${{ env.TEST_TAG }} tags: ${{ env.TEST_TAG }}
``` ```
> :bulb: Build time will not be increased with this workflow because internal > **Note**
> cache for `linux/amd64` will be used from previous step on `Build and push` >
> step so only `linux/arm64` will be actually built. > Build time will not be increased with this workflow because internal cache
> for `linux/amd64` will be used from previous step on `Build and push` step
> so only `linux/arm64` will be actually built.

2
test/Dockerfile
View File

@ -1,3 +1,3 @@
# syntax=docker/dockerfile:1
FROM alpine FROM alpine
RUN echo "Hello world!" RUN echo "Hello world!"

1
test/addhost.Dockerfile
View File

@ -1,2 +1,3 @@
# syntax=docker/dockerfile:1
FROM busybox FROM busybox
RUN cat /etc/hosts RUN cat /etc/hosts

2
test/buildcontext.Dockerfile
View File

@ -1,3 +1,3 @@
# syntax=docker/dockerfile-upstream:master # syntax=docker/dockerfile:1
FROM alpine FROM alpine
RUN cat /etc/*release RUN cat /etc/*release

1
test/cgroup.Dockerfile
View File

@ -1,2 +1,3 @@
# syntax=docker/dockerfile:1
FROM alpine FROM alpine
RUN cat /proc/self/cgroup RUN cat /proc/self/cgroup

4
test/multi-sudo.Dockerfile
View File

@ -1,9 +1,8 @@
# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:alpine AS build FROM --platform=$BUILDPLATFORM golang:alpine AS build
ARG TARGETPLATFORM ARG TARGETPLATFORM
ARG BUILDPLATFORM ARG BUILDPLATFORM
RUN echo "I am running on $BUILDPLATFORM, building for $TARGETPLATFORM" > /log RUN echo "I am running on $BUILDPLATFORM, building for $TARGETPLATFORM" > /log
RUN apk --update --no-cache add \ RUN apk --update --no-cache add \
shadow \ shadow \
sudo \ sudo \
@ -17,6 +16,5 @@ RUN sudo chown buildx. /log
USER root USER root
FROM alpine FROM alpine
COPY --from=build /log /log COPY --from=build /log /log
RUN ls -al /log RUN ls -al /log

1
test/multi.Dockerfile
View File

@ -1,3 +1,4 @@
# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:alpine AS build FROM --platform=$BUILDPLATFORM golang:alpine AS build
ARG TARGETPLATFORM ARG TARGETPLATFORM

1
test/nocachefilter.Dockerfile
View File

@ -1,3 +1,4 @@
# syntax=docker/dockerfile:1
FROM busybox AS base FROM busybox AS base
RUN echo "Hello world!" > /hello RUN echo "Hello world!" > /hello

4
test/secret.Dockerfile Normal file
View File

@ -0,0 +1,4 @@
# syntax=docker/dockerfile:1
FROM busybox
RUN --mount=type=secret,id=MYSECRET \
echo "MYSECRET=$(cat /run/secrets/MYSECRET)"

1
test/shmsize.Dockerfile
View File

@ -1,2 +1,3 @@
# syntax=docker/dockerfile:1
FROM busybox FROM busybox
RUN mount | grep /dev/shm RUN mount | grep /dev/shm

1
test/ulimit.Dockerfile
View File

@ -1,2 +1,3 @@
# syntax=docker/dockerfile:1
FROM busybox FROM busybox
RUN ulimit -a RUN ulimit -a