mirror of https://github.com/docker/docs.git
build(gha): move cache section to dedicated page
Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>
This commit is contained in:
CrazyMax
parent
9f1f00d994
commit
9412271d91
|
|
@ -1607,10 +1607,12 @@ manuals:
|
|||
section:
|
||||
- path: /build/ci/github-actions/
|
||||
title: Introduction
|
||||
- path: /build/ci/github-actions/examples/
|
||||
title: Examples
|
||||
- path: /build/ci/github-actions/configure-builder/
|
||||
title: Configuring your builder
|
||||
- path: /build/ci/github-actions/cache/
|
||||
title: Cache management
|
||||
- path: /build/ci/github-actions/examples/
|
||||
title: Examples
|
||||
- sectiontitle: Bake
|
||||
section:
|
||||
- path: /build/bake/
|
||||
|
|
|
|||
|
|
@ -0,0 +1,218 @@
|
|||
---
|
||||
title: Cache management with GitHub Actions
|
||||
keywords: ci, github actions, gha, buildkit, buildx, cache
|
||||
---
|
||||
|
||||
This page contains examples on using the cache storage backends with GitHub
|
||||
Actions.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> See [Cache storage backends](../../cache/backends/index.md) for more
|
||||
> details about cache storage backends.
|
||||
|
||||
## Inline cache
|
||||
|
||||
In most cases you want to use the [inline cache exporter](../../cache/backends/inline.md).
|
||||
However, note that the `inline` cache exporter only supports `min` cache mode.
|
||||
To use `max` cache mode, push the image and the cache separately using the
|
||||
registry cache exporter with the `cache-to` option, as shown in the [registry cache example](#registry-cache).
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
name: ci
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- "main"
|
||||
|
||||
jobs:
|
||||
docker:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
-
|
||||
name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
-
|
||||
name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v2
|
||||
-
|
||||
name: Login to Docker Hub
|
||||
uses: docker/login-action@v2
|
||||
with:
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
-
|
||||
name: Build and push
|
||||
uses: docker/build-push-action@v4
|
||||
with:
|
||||
context: .
|
||||
push: true
|
||||
tags: user/app:latest
|
||||
cache-from: type=registry,ref=user/app:latest
|
||||
cache-to: type=inline
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## Registry cache
|
||||
|
||||
You can import/export cache from a cache manifest or (special) image
|
||||
configuration on the registry with the [registry cache exporter](../../cache/backends/registry.md).
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
name: ci
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- "main"
|
||||
|
||||
jobs:
|
||||
docker:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
-
|
||||
name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
-
|
||||
name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v2
|
||||
-
|
||||
name: Login to Docker Hub
|
||||
uses: docker/login-action@v2
|
||||
with:
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
-
|
||||
name: Build and push
|
||||
uses: docker/build-push-action@v4
|
||||
with:
|
||||
context: .
|
||||
push: true
|
||||
tags: user/app:latest
|
||||
cache-from: type=registry,ref=user/app:buildcache
|
||||
cache-to: type=registry,ref=user/app:buildcache,mode=max
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## GitHub cache
|
||||
|
||||
### Cache backend API
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> This cache exporter is experimental. Please provide feedback on [BuildKit repository](https://github.com/moby/buildkit){:target="blank" rel="noopener" class=""}
|
||||
> if you experience any issues.
|
||||
{: .warning }
|
||||
|
||||
The [GitHub Actions cache exporter](../../cache/backends/gha.md)
|
||||
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 you should only use this cache
|
||||
backend in a GitHub Action workflow, as the `url` (`$ACTIONS_CACHE_URL`) and
|
||||
`token` (`$ACTIONS_RUNTIME_TOKEN`) attributes only get populated in a workflow
|
||||
context.
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
name: ci
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- "main"
|
||||
|
||||
jobs:
|
||||
docker:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
-
|
||||
name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
-
|
||||
name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v2
|
||||
-
|
||||
name: Login to Docker Hub
|
||||
uses: docker/login-action@v2
|
||||
with:
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
-
|
||||
name: Build and push
|
||||
uses: docker/build-push-action@v4
|
||||
with:
|
||||
context: .
|
||||
push: true
|
||||
tags: user/app:latest
|
||||
cache-from: type=gha
|
||||
cache-to: type=gha,mode=max
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### Local cache
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> At the moment, old cache entries aren't deleted, so the cache size [keeps growing](https://github.com/docker/build-push-action/issues/252){:target="blank" rel="noopener" class=""}.
|
||||
> The following example uses the `Move cache` step as a workaround (see [`moby/buildkit#1896`](https://github.com/moby/buildkit/issues/1896){:target="blank" rel="noopener" class=""}
|
||||
> for more info).
|
||||
{: .warning }
|
||||
|
||||
You can also leverage [GitHub cache](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows){:target="blank" rel="noopener" class=""}
|
||||
using the [actions/cache](https://github.com/actions/cache) and [local cache exporter](../../cache/backends/local.md)
|
||||
with this action:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
name: ci
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- "main"
|
||||
|
||||
jobs:
|
||||
docker:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
-
|
||||
name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
-
|
||||
name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v2
|
||||
-
|
||||
name: Cache Docker layers
|
||||
uses: actions/cache@v3
|
||||
with:
|
||||
path: /tmp/.buildx-cache
|
||||
key: ${{ runner.os }}-buildx-${{ github.sha }}
|
||||
restore-keys: |
|
||||
${{ runner.os }}-buildx-
|
||||
-
|
||||
name: Login to Docker Hub
|
||||
uses: docker/login-action@v2
|
||||
with:
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
-
|
||||
name: Build and push
|
||||
uses: docker/build-push-action@v4
|
||||
with:
|
||||
context: .
|
||||
push: true
|
||||
tags: user/app:latest
|
||||
cache-from: type=local,src=/tmp/.buildx-cache
|
||||
cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max
|
||||
-
|
||||
# Temp fix
|
||||
# https://github.com/docker/build-push-action/issues/252
|
||||
# https://github.com/moby/buildkit/issues/1896
|
||||
name: Move cache
|
||||
run: |
|
||||
rm -rf /tmp/.buildx-cache
|
||||
mv /tmp/.buildx-cache-new /tmp/.buildx-cache
|
||||
```
|
||||
{% endraw %}
|
||||
|
|
@ -194,222 +194,6 @@ jobs:
|
|||
|
||||
{% endraw %}
|
||||
|
||||
## Cache
|
||||
|
||||
This page contains examples on using the cache storage backends with GitHub
|
||||
actions.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> See [Cache storage backends](../../cache/backends/index.md) for more
|
||||
> details about cache storage backends.
|
||||
|
||||
### Inline cache
|
||||
|
||||
In most cases you want to use the [inline cache exporter](../../cache/backends/inline.md).
|
||||
However, note that the `inline` cache exporter only supports `min` cache mode.
|
||||
To use `max` cache mode, push the image and the cache separately using the
|
||||
registry cache exporter with the `cache-to` option, as shown in the [registry cache example](#registry-cache).
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
name: ci
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- "main"
|
||||
|
||||
jobs:
|
||||
docker:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
-
|
||||
name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
-
|
||||
name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v2
|
||||
-
|
||||
name: Login to Docker Hub
|
||||
uses: docker/login-action@v2
|
||||
with:
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
-
|
||||
name: Build and push
|
||||
uses: docker/build-push-action@v4
|
||||
with:
|
||||
context: .
|
||||
push: true
|
||||
tags: user/app:latest
|
||||
cache-from: type=registry,ref=user/app:latest
|
||||
cache-to: type=inline
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### Registry cache
|
||||
|
||||
You can import/export cache from a cache manifest or (special) image
|
||||
configuration on the registry with the [registry cache exporter](../../cache/backends/registry.md).
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
name: ci
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- "main"
|
||||
|
||||
jobs:
|
||||
docker:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
-
|
||||
name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
-
|
||||
name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v2
|
||||
-
|
||||
name: Login to Docker Hub
|
||||
uses: docker/login-action@v2
|
||||
with:
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
-
|
||||
name: Build and push
|
||||
uses: docker/build-push-action@v4
|
||||
with:
|
||||
context: .
|
||||
push: true
|
||||
tags: user/app:latest
|
||||
cache-from: type=registry,ref=user/app:buildcache
|
||||
cache-to: type=registry,ref=user/app:buildcache,mode=max
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### GitHub cache
|
||||
|
||||
#### Cache backend API
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> This cache exporter is experimental. Please provide feedback on [BuildKit repository](https://github.com/moby/buildkit){:target="blank" rel="noopener" class=""}
|
||||
> if you experience any issues.
|
||||
{: .warning }
|
||||
|
||||
The [GitHub Actions cache exporter](../../cache/backends/gha.md)
|
||||
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 you should only use this cache
|
||||
backend in a GitHub Action workflow, as the `url` (`$ACTIONS_CACHE_URL`) and
|
||||
`token` (`$ACTIONS_RUNTIME_TOKEN`) attributes only get populated in a workflow
|
||||
context.
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
name: ci
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- "main"
|
||||
|
||||
jobs:
|
||||
docker:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
-
|
||||
name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
-
|
||||
name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v2
|
||||
-
|
||||
name: Login to Docker Hub
|
||||
uses: docker/login-action@v2
|
||||
with:
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
-
|
||||
name: Build and push
|
||||
uses: docker/build-push-action@v4
|
||||
with:
|
||||
context: .
|
||||
push: true
|
||||
tags: user/app:latest
|
||||
cache-from: type=gha
|
||||
cache-to: type=gha,mode=max
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
#### Local cache
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> At the moment, old cache entries aren't deleted, so the cache size [keeps growing](https://github.com/docker/build-push-action/issues/252){:target="blank" rel="noopener" class=""}.
|
||||
> The following example uses the `Move cache` step as a workaround (see [`moby/buildkit#1896`](https://github.com/moby/buildkit/issues/1896){:target="blank" rel="noopener" class=""}
|
||||
> for more info).
|
||||
{: .warning }
|
||||
|
||||
You can also leverage [GitHub cache](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows){:target="blank" rel="noopener" class=""}
|
||||
using the [actions/cache](https://github.com/actions/cache) and [local cache exporter](../../cache/backends/local.md)
|
||||
with this action:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
name: ci
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- "main"
|
||||
|
||||
jobs:
|
||||
docker:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
-
|
||||
name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
-
|
||||
name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v2
|
||||
-
|
||||
name: Cache Docker layers
|
||||
uses: actions/cache@v3
|
||||
with:
|
||||
path: /tmp/.buildx-cache
|
||||
key: ${{ runner.os }}-buildx-${{ github.sha }}
|
||||
restore-keys: |
|
||||
${{ runner.os }}-buildx-
|
||||
-
|
||||
name: Login to Docker Hub
|
||||
uses: docker/login-action@v2
|
||||
with:
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
-
|
||||
name: Build and push
|
||||
uses: docker/build-push-action@v4
|
||||
with:
|
||||
context: .
|
||||
push: true
|
||||
tags: user/app:latest
|
||||
cache-from: type=local,src=/tmp/.buildx-cache
|
||||
cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max
|
||||
-
|
||||
# Temp fix
|
||||
# https://github.com/docker/build-push-action/issues/252
|
||||
# https://github.com/moby/buildkit/issues/1896
|
||||
name: Move cache
|
||||
run: |
|
||||
rm -rf /tmp/.buildx-cache
|
||||
mv /tmp/.buildx-cache-new /tmp/.buildx-cache
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## Secrets
|
||||
|
||||
In the following example uses and exposes the [`GITHUB_TOKEN` secret](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret){:target="blank" rel="noopener" class=""}
|
||||
|
|
|
|||
|
|
@ -43,5 +43,4 @@ using the official Docker actions, to build and push an image to Docker Hub.
|
|||
There are many more things you can do to customize your workflow to better suit
|
||||
your needs. To learn more about some of the more advanced use cases, take a look
|
||||
at the advanced examples, such as [building multi-platform images](examples.md#multi-platform-images),
|
||||
or [using cache storage backends](examples.md#cache) and also how to
|
||||
[configure your builder](configure-builder.md).
|
||||
or [using cache storage backends](cache.md) and also how to [configure your builder](configure-builder.md).
|
||||
|
|
|
|||
Loading…
Reference in New Issue