GitHub Actions 快取

可用性：實驗性功能

GitHub Actions 快取利用 GitHub 提供的 Action 快取或其他支援 GitHub Actions 快取協定的快取服務。只要您的使用案例符合 GitHub 設定的大小與使用限制，這是在 GitHub Actions 工作流程中使用時推薦的快取方式。

此快取儲存後端不支援預設的 docker 驅動程式。若要使用此功能，請使用不同的驅動程式建立新的 builder。詳情請參閱建置驅動程式。

概要

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=gha[,parameters...] \
  --cache-from type=gha[,parameters...] .

下表說明了您可以傳遞給 --cache-to 和 --cache-from 的可用 CSV 參數。

名稱	選項	類型	預設值	描述
`url`	`cache-to`, `cache-from`	String	`$ACTIONS_CACHE_URL` 或 `$ACTIONS_RESULTS_URL`	快取伺服器 URL，請參閱身分驗證。
`url_v2`	`cache-to`, `cache-from`	String	`$ACTIONS_RESULTS_URL`	快取 v2 伺服器 URL，請參閱身分驗證。
`token`	`cache-to`, `cache-from`	String	`$ACTIONS_RUNTIME_TOKEN`	存取權杖，請參閱身分驗證。
`scope`	`cache-to`, `cache-from`	String	`buildkit`	快取物件所屬的範圍，請參閱範圍 (scope)
`模式`	`cache-to`	`min`,`max`	`min`	要匯出的快取層，請參閱快取模式。
`ignore-error`	`cache-to`	布林值	`false`	忽略因快取匯出失敗而導致的錯誤。
`timeout`	`cache-to`, `cache-from`	String	`10m`	匯入或匯出快取的逾時上限。
`repository`	`cache-to`	String		用於快取儲存的 GitHub 儲存庫。
`ghtoken`	`cache-to`	String		存取 GitHub API 所需的 GitHub 權杖。

驗證

若未指定 url、url_v2 或 token 參數，gha 快取後端將會退回到使用環境變數。若您手動從內嵌步驟呼叫 docker buildx 指令，則必須手動公開這些變數。建議使用 crazy-max/ghaction-github-runtime GitHub Action 作為公開變數的輔助工具。

範圍

範圍 (Scope) 是用於識別快取物件的鍵值。預設設定為 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 簡介

GitHub Actions 快取

概要

驗證

範圍

使用 docker/build-push-action

避免 GitHub Actions 快取 API 頻率限制

延伸閱讀

使用 `docker/build-push-action`