GitHub Actions 缓存

目录
可用性： 实验性

GitHub Actions 缓存利用了 GitHub 提供的 Action 缓存或支持 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 或 $ACTIONS_RESULTS_URL缓存服务器 URL，请参阅身份验证。
url_v2cache-to,cache-from字符串$ACTIONS_RESULTS_URL缓存 v2 服务器 URL，请参阅身份验证。
令牌cache-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 作为暴露变量的帮助程序。

作用域

作用域是用于识别缓存对象的键。默认情况下，它设置为 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 所必需的。

当您使用 docker/build-push-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 README。

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

© . This site is unofficial and not affiliated with Kubernetes or Docker Inc.