From 58c3cb8158442c06153c6cd8c93139959776ad56 Mon Sep 17 00:00:00 2001 From: CrazyMax Date: Mon, 12 Jul 2021 15:50:38 +0200 Subject: [PATCH] GitHub Actions cache docs Signed-off-by: CrazyMax --- README.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 590b435365b27..cb2b3e95f4bc1 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,7 @@ You don't need to read this document unless you want to use the full-featured st - [Inline (push image and cache together)](#inline-push-image-and-cache-together) - [Registry (push image and cache separately)](#registry-push-image-and-cache-separately) - [Local directory](#local-directory-1) + - [GitHub Actions cache](#github-actions-cache) - [`--export-cache` options](#--export-cache-options) - [`--import-cache` options](#--import-cache-options) - [Consistent hashing](#consistent-hashing) @@ -314,6 +315,7 @@ BuildKit supports the following cache exporters: * `inline`: embed the cache into the image, and push them to the registry together * `registry`: push the image and the cache separately * `local`: export to a local directory +* `gha`: export to GitHub Actions cache In most case you want to use the `inline` cache exporter. However, note that the `inline` cache exporter only supports `min` cache mode. @@ -340,7 +342,7 @@ However, the standalone `buildctl` does NOT require `--opt build-arg:BUILDKIT_IN buildctl build ... \ --output type=image,name=localhost:5000/myrepo:image,push=true \ --export-cache type=registry,ref=localhost:5000/myrepo:buildcache \ - --import-cache type=registry,ref=localhost:5000/myrepo:buildcache \ + --import-cache type=registry,ref=localhost:5000/myrepo:buildcache ``` #### Local directory @@ -352,18 +354,36 @@ buildctl build ... --import-cache type=local,src=path/to/input-dir The directory layout conforms to OCI Image Spec v1.0. +#### GitHub Actions cache + +```bash +buildctl build ... \ + --output type=image,name=docker.io/username/image,push=true \ + --export-cache type=gha \ + --import-cache type=gha +``` + +Following attributes are required to authenticate against the [Github Actions Cache service API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md#authentication): +* `url`: Cache server URL (default `$ACTIONS_CACHE_URL`) +* `token`: Access token (default `$ACTIONS_RUNTIME_TOKEN`) + +:information_source: This cache should be used exclusively in a [GitHub Action](https://github.com/features/actions) +workflow to be able to retrieve the cache `url` and `token` exposed by the [runner](https://github.com/actions/runner). + #### `--export-cache` options -- `type`: `inline`, `registry`, or `local` +- `type`: `inline`, `registry`, `local` or `gha` - `mode=min` (default): only export layers for the resulting image -- `mode=max`: export all the layers of all intermediate steps. Not supported for `inline` cache exporter. +- `mode=max`: export all the layers of all intermediate steps. Not supported for `inline` and `gha` cache exporter. - `ref=docker.io/user/image:tag`: reference for `registry` cache exporter - `dest=path/to/output-dir`: directory for `local` cache exporter +- `scope=buildkit`: scope for `gha` cache exporter (default `buildkit`) - `oci-mediatypes=true|false`: whether to use OCI mediatypes in exported manifests for `local` and `registry` exporter. Since BuildKit `v0.8` defaults to true. #### `--import-cache` options -- `type`: `registry` or `local`. Use `registry` to import `inline` cache. +- `type`: `registry`, `local` or `gha`. Use `registry` to import `inline` cache. - `ref=docker.io/user/image:tag`: reference for `registry` cache importer - `src=path/to/input-dir`: directory for `local` cache importer +- `scope=buildkit`: scope for `gha` cache importer (default `buildkit`) - `digest=sha256:deadbeef`: digest of the manifest list to import for `local` cache importer. - `tag=customtag`: custom tag of image for `local` cache importer. Defaults to the digest of "latest" tag in `index.json` is for digest, not for tag