GitHub Actions 缓存

目录
可用性： 实验性

GitHub Actions 缓存利用了GitHub 提供的 Action 缓存或支持 GitHub Actions 缓存协议的其他缓存服务。这是在 GitHub Actions 工作流中推荐使用的缓存，只要你的用例符合GitHub 设定的大小和使用限制。

默认的 docker 驱动程序不支持此缓存存储后端。要使用此功能，请创建一个新的使用不同驱动程序的构建器。详情请参见构建驱动程序。

概要

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=gha[,parameters...] \
  --cache-from type=gha[,parameters...] .

下表描述了可以传递给 --cache-to 和 --cache-from 的可用 CSV 参数。

名称选项类型默认值描述
urlcache-to,cache-from字符串$ACTIONS_CACHE_URL缓存服务器 URL，详情请参见认证。
url_v2cache-to,cache-from字符串$ACTIONS_CACHE_URL缓存 v2 服务器 URL，详情请参见认证。
tokencache-to,cache-from字符串$ACTIONS_RUNTIME_TOKEN访问令牌，详情请参见认证。
scopecache-to,cache-from字符串buildkit缓存对象所属的范围，详情请参见范围。
modecache-tomin,maxmin要导出的缓存层，详情请参见缓存模式。
ignore-errorcache-to布尔值false忽略因缓存导出失败引起的错误。
timeoutcache-to,cache-from字符串10m导入或导出缓存的最大持续时间，超过此时间则超时。
repositorycache-to字符串用于缓存存储的 GitHub 仓库。
ghtokencache-to字符串访问 GitHub API 所需的 GitHub 令牌。

认证

如果 url、url_v2 或 token 参数未指定，gha 缓存后端将回退到使用环境变量。如果你从内联步骤手动调用 docker buildx 命令，那么这些变量必须手动暴露。考虑使用crazy-max/ghaction-github-runtime这个 GitHub Action 作为暴露变量的辅助工具。

范围

Scope 是用于标识缓存对象的键。默认情况下，它设置为 buildkit。如果你构建多个镜像，每次构建都会覆盖之前的缓存，只留下最终的缓存。

为了为多次构建保留缓存，你可以使用特定名称指定此 scope 属性。在以下示例中，缓存设置为镜像名称，以确保每个镜像都有自己的缓存。

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=gha,url=...,token=...,scope=image \
  --cache-from type=gha,url=...,token=...,scope=image .
$ docker buildx build --push -t <registry>/<image2> \
  --cache-to type=gha,url=...,token=...,scope=image2 \
  --cache-from type=gha,url=...,token=...,scope=image2 .

GitHub 的缓存访问限制仍然适用。工作流只能访问当前分支、基础分支和默认分支的缓存。

使用 docker/build-push-action

使用docker/build-push-action时，url 和 token 参数会自动填充。无需手动指定它们，也无需包含任何其他变通方法。

例如

- name: Build and push
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: "<registry>/<image>:latest"
    cache-from: type=gha
    cache-to: type=gha,mode=max

避免 GitHub Actions 缓存 API 节流

GitHub 的使用限制和清除策略会导致过期缓存条目在一定时间后被移除。默认情况下，gha 缓存后端使用 GitHub Actions 缓存 API 来检查缓存条目的状态。

如果你在短时间内发出太多请求，GitHub Actions 缓存 API 会受到速率限制，这在使用 gha 缓存后端进行构建期间进行缓存查找时可能会发生。

#31 exporting to GitHub Actions Cache
#31 preparing build cache for export
#31 preparing build cache for export 600.3s done
#31 ERROR: maximum timeout reached
------
 > exporting to GitHub Actions Cache:
------
ERROR: failed to solve: maximum timeout reached
make: *** [Makefile:35: release] Error 1
Error: Process completed with exit code 2.

为了缓解此问题，你可以向 BuildKit 提供一个 GitHub 令牌。这使得 BuildKit 可以利用标准 GitHub API 检查缓存键，从而减少对缓存 API 的请求次数。

要提供 GitHub 令牌，你可以使用 ghtoken 参数，并使用 repository 参数指定用于缓存存储的仓库。ghtoken 参数是具有 repo 范围的 GitHub 令牌，访问 GitHub Actions 缓存 API 需要此令牌。

使用 docker/build-push-action action 进行构建时，ghtoken 参数会自动设置为 secrets.GITHUB_TOKEN 的值。你也可以使用 github-token 输入手动设置 ghtoken 参数，如下例所示：

- name: Build and push
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: "<registry>/<image>:latest"
    cache-from: type=gha
    cache-to: type=gha,mode=max
    github-token: ${{ secrets.MY_CUSTOM_TOKEN }}

进一步阅读

缓存介绍请参见Docker Build 缓存。

关于 gha 缓存后端的更多信息，请参见BuildKit README。

关于在 Docker 中使用 GitHub Actions 的更多信息，请参见GitHub Actions 介绍

页面选项