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-from字符串$ACTIONS_CACHE_URL缓存服务器 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或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 token。这允许 BuildKit 利用标准的 GitHub API 来检查缓存密钥，从而减少对缓存 API 的请求次数。

要提供 GitHub token，您可以使用 ghtoken 参数，并使用 repository 参数指定用于缓存存储的仓库。ghtoken 参数是一个具有 repo 作用域的 GitHub token，这是访问 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 构建缓存。

有关 gha 缓存后端的更多信息，请参阅BuildKit 自述文件。

有关使用 GitHub Actions 和 Docker 的更多信息，请参阅GitHub Actions 简介