From 9412271d91208968a0df14053e58d7e0b8511481 Mon Sep 17 00:00:00 2001 From: CrazyMax Date: Thu, 23 Feb 2023 00:55:34 +0100 Subject: [PATCH] build(gha): move cache section to dedicated page Signed-off-by: CrazyMax --- _data/toc.yaml | 6 +- build/ci/github-actions/cache.md | 218 ++++++++++++++++++++++++++++ build/ci/github-actions/examples.md | 216 --------------------------- build/ci/github-actions/index.md | 3 +- 4 files changed, 223 insertions(+), 220 deletions(-) create mode 100644 build/ci/github-actions/cache.md diff --git a/_data/toc.yaml b/_data/toc.yaml index 45303e5c77..dd188f2836 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -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/ diff --git a/build/ci/github-actions/cache.md b/build/ci/github-actions/cache.md new file mode 100644 index 0000000000..072ffbdeab --- /dev/null +++ b/build/ci/github-actions/cache.md @@ -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 %} diff --git a/build/ci/github-actions/examples.md b/build/ci/github-actions/examples.md index 9793a93760..ebb1a2b891 100644 --- a/build/ci/github-actions/examples.md +++ b/build/ci/github-actions/examples.md @@ -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=""} diff --git a/build/ci/github-actions/index.md b/build/ci/github-actions/index.md index bc79a5de2f..9bfd988a81 100644 --- a/build/ci/github-actions/index.md +++ b/build/ci/github-actions/index.md @@ -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).