切换语言

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.

名字选择类型违约描述
urlcache-to,cache-from字符串$ACTIONS_CACHE_URL缓存服务器 URL，请参阅 身份验证。
tokencache-to,cache-from字符串$ACTIONS_RUNTIME_TOKENAccess 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或tokenparameters 未指定，则gha缓存后端 将回退到使用环境变量。如果调用docker buildx命令，则必须手动将变量 暴露。考虑使用crazy-max/ghaction-github-runtime, GitHub Action 作为公开变量的帮助程序。

范围

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

要为多个构建保留缓存，您可以指定此 scope 属性 替换为特定名称。在以下示例中，缓存设置为镜像 name 的 Alpha S Package，以确保每个

$ 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 的缓存访问限制， 仍然适用。只有当前分支、基本分支和 default 分支可由工作流访问。

用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 的使用限制和驱逐策略会导致过时的缓存条目在一段时间后被删除。由 default、ghacache 后端使用 GitHub Actions 缓存 API 检查 缓存条目的状态。

如果您创建过多的 GitHub Actions 缓存 API ，则 GitHub Actions 缓存 API 会受到速率限制 请求，这可能是缓存的结果 在构建过程中使用ghacache 后端。

#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 令牌，您可以使用ghtokenparameter 和repository参数指定要用于缓存存储的存储库。这ghtokenparameter 是 GitHub 令牌，其reposcope，这是必需的 以访问 GitHub Actions 缓存 API。

这ghtoken参数会自动设置为secrets.GITHUB_TOKEN当您使用docker/build-push-action行动。您还可以设置ghtoken参数，使用github-tokeninput，如以下示例所示：

- 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 构建缓存。

有关ghacache 后端，请参阅 BuildKit README。

有关将 GitHub Actions 与 Docker 结合使用的更多信息，请参阅 GitHub Actions 简介