切换语言

GitHub Actions 缓存

目录

受限

这是一个实验性功能。界面和行为不稳定，未来版本可能会更改。

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

此缓存存储后端不支持默认的 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-fromstring$ACTIONS_CACHE_URL缓存服务器 URL，请参阅 身份验证。
tokencache-to,cache-fromstring$ACTIONS_RUNTIME_TOKEN访问令牌，请参阅 身份验证。
scopecache-to,cache-fromstringbuildkit缓存对象所属的作用域，参见 作用域
modecache-tomin,maxmin导出的缓存层，请参阅 缓存模式。
ignore-errorcache-to布尔值false忽略由缓存导出失败引起的错误。
timeoutcache-to,cache-fromstring10m导入或导出缓存的最大持续时间，超过将超时。
repositorycache-tostring用于缓存存储的 GitHub 仓库。
ghtokencache-tostring访问 GitHub API 需要 GitHub 令牌。

认证

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

范围

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

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

$ 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 所必需的。

ghtoken 参数在使用 docker/build-push-action 操作构建时会自动设置为 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 构建缓存。

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

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