Cache backend API example

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

.github/workflows/ci.yml

@@ -503,7 +503,7 @@ jobs:
         if: always()
         uses: crazy-max/ghaction-dump-context@v1
 
-  github-cache-first:
+  local-cache-first:
     runs-on: ubuntu-latest
     outputs:
       digest: ${{ steps.docker_build.outputs.digest }}
@@ -531,7 +531,7 @@ jobs:
         uses: actions/cache@v2
         with:
           path: /tmp/.buildx-cache
-          key: ${{ runner.os }}-buildx-ghcache-${{ github.sha }}
+          key: ${{ runner.os }}-buildx-local-${{ github.sha }}
           restore-keys: |
             ${{ runner.os }}-buildx-ghcache-
       -
@@ -572,9 +572,9 @@ jobs:
         if: always()
         uses: crazy-max/ghaction-dump-context@v1
 
-  github-cache-hit:
+  local-cache-hit:
     runs-on: ubuntu-latest
-    needs: github-cache-first
+    needs: local-cache-first
     services:
       registry:
         image: registry:2
@@ -600,7 +600,7 @@ jobs:
         id: cache
         with:
           path: /tmp/.buildx-cache
-          key: ${{ runner.os }}-buildx-ghcache-${{ github.sha }}
+          key: ${{ runner.os }}-buildx-local-${{ github.sha }}
           restore-keys: |
             ${{ runner.os }}-buildx-ghcache-
       -
@@ -635,8 +635,8 @@ jobs:
       -
         name: Compare digests
         run: |
-          echo Compare "${{ needs.github-cache-first.outputs.digest }}" with "${{ steps.docker_build.outputs.digest }}"
-          if [ "${{ needs.github-cache-first.outputs.digest }}" != "${{ steps.docker_build.outputs.digest }}" ]; then
+          echo Compare "${{ needs.local-cache-first.outputs.digest }}" with "${{ steps.docker_build.outputs.digest }}"
+          if [ "${{ needs.local-cache-first.outputs.digest }}" != "${{ steps.docker_build.outputs.digest }}" ]; then
             echo "::error::Digests should be identical"
             exit 1
           fi
@@ -647,3 +647,60 @@ jobs:
         name: Dump context
         if: always()
         uses: crazy-max/ghaction-dump-context@v1
+
+  github-cache:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        buildx_version:
+          - v0.6.0
+          - latest
+        buildkit_version:
+          - buildx-stable-1
+          - latest
+    services:
+      registry:
+        image: registry:2
+        ports:
+          - 5000:5000
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2
+      -
+        name: Set up QEMU
+        uses: docker/setup-qemu-action@v1
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+        with:
+          version: ${{ matrix.buildx_version }}
+          driver-opts: |
+            image=moby/buildkit:${{ matrix.buildkit_version }}
+            network=host
+          buildkitd-flags: --debug
+      -
+        name: Build and push
+        uses: ./
+        with:
+          context: ./test
+          file: ./test/multi.Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            localhost:5000/name/app:latest
+            localhost:5000/name/app:1.0.0
+          cache-from: type=gha,scope=ci-${{ matrix.buildx_version }}-${{ matrix.buildkit_version }}
+          cache-to: type=gha,scope=ci-${{ matrix.buildx_version }}-${{ matrix.buildkit_version }}
+      -
+        name: Inspect
+        run: |
+          docker buildx imagetools inspect localhost:5000/name/app:1.0.0
+      -
+        name: Image digest
+        run: echo ${{ steps.docker_build.outputs.digest }}
+      -
+        name: Dump context
+        if: always()
+        uses: crazy-max/ghaction-dump-context@v1

docs/advanced/cache.md

@@ -2,6 +2,8 @@
 
 * [Registry cache](#registry-cache)
 * [GitHub cache](#github-cache)
+  * [Cache backend API (experimental)](#cache-backend-api-experimental)
+  * [Local cache](#local-cache)
 
 > More info about buildx cache: https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#cache-from
 
@@ -46,13 +48,57 @@ jobs:
 
 ## GitHub cache
 
+### Cache backend API (experimental)
+
+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),
+you can use the [`type=gha` cache exporter](https://github.com/moby/buildkit/tree/master#github-actions-cache-experimental).
+
+GitHub Actions cache exporter 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 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.
+
+```yaml
+name: ci
+
+on:
+  push:
+    branches:
+      - 'master'
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+      -
+        name: Login to DockerHub
+        uses: docker/login-action@v1 
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      -
+        name: Build and push
+        uses: docker/build-push-action@v2
+        with:
+          context: .
+          push: true
+          tags: user/app:latest
+          cache-from: type=gha
+          cache-to: type=gha
+```
+
+### 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).
 > The `Move cache` step is used as a temporary fix (see https://github.com/moby/buildkit/issues/1896).
 
-> :rocket: There is a new cache backend using GitHub cache being developed that will lighten your workflow.
-> More info: https://github.com/docker/buildx/pull/535
-
-You can 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/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows)
 using [actions/cache](https://github.com/actions/cache) with this action:
 
 ```yaml