使用 GitHub Actions 進行快取管理

本頁面包含有關如何搭配 GitHub Actions 使用快取儲存後端的範例。

注意
關於快取儲存後端的詳細資訊，請參閱快取儲存後端。

內嵌快取

大多數情況下，您會希望使用內嵌 (inline) 快取匯出工具。但請注意，inline 快取匯出工具僅支援 min 快取模式。若要使用 max 快取模式，請使用 registry 快取匯出工具搭配 cache-to 選項來分別推送映像檔和快取，如registry 快取範例所示。

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          push: true
          tags: user/app:latest
          cache-from: type=registry,ref=user/app:latest
          cache-to: type=inline

登錄檔快取

您可以利用registry 快取匯出工具，從 registry 上的快取資訊清單或（特殊）映像檔設定匯入/匯出快取。

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          push: true
          tags: user/app:latest
          cache-from: type=registry,ref=user/app:buildcache
          cache-to: type=registry,ref=user/app:buildcache,mode=max

GitHub 快取

快取後端 API

可用性：實驗性功能

GitHub Actions 快取匯出工具後端會使用 GitHub 快取服務 API 來擷取和上傳快取 Blob。因此，您應該僅在 GitHub Action 工作流程中使用此快取後端，因為 url ($ACTIONS_RESULTS_URL) 和 token ($ACTIONS_RUNTIME_TOKEN) 屬性僅會在工作流程環境中填入。

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          push: true
          tags: user/app:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

重要
自 2025 年 4 月 15 日起，僅支援 GitHub 快取服務 API v2。
如果您在建置過程中遇到以下錯誤
ERROR: failed to solve: This legacy service is shutting down, effective April 15, 2025. Migrate to the new service ASAP. For more information: https://gh.io/gha-cache-sunset
您可能使用了僅支援舊版 GitHub 快取服務 API v1 的過時工具。根據您的使用案例，您需要升級至以下最低版本：
Docker Buildx >= v0.21.0
BuildKit >= v0.20.0
Docker Compose >= v2.33.1
Docker Engine >= v28.0.0（如果您是在啟用 containerd 映像檔儲存的情況下使用 Docker 驅動程式進行建置）
如果您是在 GitHub 託管的執行器 (GitHub hosted runners) 上使用 docker/build-push-action 或 docker/bake-action 動作進行建置，Docker Buildx 和 BuildKit 已經是最新版本；但在自架執行器 (self-hosted runners) 上，您可能需要自行更新它們。或者，您可以使用 docker/setup-buildx-action 動作來安裝最新版本的 Docker Buildx。
- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
  with:
   version: latest
如果您是使用 Docker Compose 進行建置，可以使用 docker/setup-compose-action 動作。
- name: Set up Docker Compose
  uses: docker/setup-compose-action@v1
  with:
   version: latest
如果您是在啟用 containerd 映像檔儲存的情況下使用 Docker Engine 進行建置，可以使用 docker/setup-docker-action 動作。
-
  name: Set up Docker
  uses: docker/setup-docker-action@v4
  with:
    version: latest
    daemon-config: |
      {
        "features": {
          "containerd-snapshotter": true
        }
      }

快取掛載 (Cache mounts)

BuildKit 預設不會在 GitHub Actions 快取中保留快取掛載。若要將快取掛載放入 GitHub Actions 快取並在各個建置之間重複使用，可以使用 reproducible-containers/buildkit-cache-dance 提供的變通方法。

此 GitHub Action 會建立臨時容器，以在您的 Docker 建置步驟中提取和注入快取掛載資料。

以下範例展示了如何針對 Go 專案使用此變通方法。

build/package/Dockerfile 中的範例 Dockerfile

FROM golang:1.21.1-alpine as base-build

WORKDIR /build
RUN go env -w GOMODCACHE=/root/.cache/go-build

COPY go.mod go.sum ./
RUN --mount=type=cache,target=/root/.cache/go-build go mod download

COPY ./src ./
RUN --mount=type=cache,target=/root/.cache/go-build go build -o /bin/app /build/src
...

CI 動作範例

name: ci

on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Docker meta
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: user/app
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}

      - name: Go Build Cache for Docker
        uses: actions/cache@v4
        with:
          path: go-build-cache
          key: ${{ runner.os }}-go-build-cache-${{ hashFiles('**/go.sum') }}

      - name: Inject go-build-cache
        uses: reproducible-containers/buildkit-cache-dance@4b2444fec0c0fb9dbf175a96c094720a692ef810 # v2.1.4
        with:
          cache-source: go-build-cache

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          cache-from: type=gha
          cache-to: type=gha,mode=max
          file: build/package/Dockerfile
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          platforms: linux/amd64,linux/arm64

如需有關此變通方法的更多資訊，請參閱 GitHub 儲存庫。

本機快取

警告
目前舊的快取項目不會被刪除，因此快取大小會持續增加。以下範例使用 Move cache 步驟作為變通方法（詳細資訊請參閱 moby/buildkit#1896）。

您也可以搭配此動作使用 actions/cache 和本機快取匯出工具，來運用 GitHub 快取。

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Cache Docker layers
        uses: actions/cache@v4
        with:
          path: ${{ runner.temp }}/.buildx-cache
          key: ${{ runner.os }}-buildx-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-buildx-

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          push: true
          tags: user/app:latest
          cache-from: type=local,src=${{ runner.temp }}/.buildx-cache
          cache-to: type=local,dest=${{ runner.temp }}/.buildx-cache-new,mode=max

      - # Temp fix
        # https://github.com/docker/build-push-action/issues/252
        # https://github.com/moby/buildkit/issues/1896
        name: Move cache
        run: |
          rm -rf ${{ runner.temp }}/.buildx-cache
          mv ${{ runner.temp }}/.buildx-cache-new ${{ runner.temp }}/.buildx-cache