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 簡介