GitLab Runner: 建立 Docker 映像檔

使用 Stackhero runner 與 Docker-in-Docker，從您的 GitLab CI/CD pipeline 高效建置與推送 Docker 映像檔

👋 歡迎來到 Stackhero 文件中心！

Stackhero 為您提供一套易於使用的 GitLab Runner cloud 解決方案，專為高效處理您的 GitLab CI/CD 任務而設計。您可以期待以下優勢：

• 無限制 CI/CD 時數：不採用按分鐘計費，您的 pipeline 可隨時執行。
• 多任務並行執行：可同時運行多個任務，加速整體 pipeline 流程。
• 支援 Docker executor 及 Docker-in-Docker：簡化容器映像檔的建置與推送流程。
• 相容於 GitLab.com 及任何 自建 GitLab 實例。
• 專屬私人虛擬機（VM），採用高速 NVMe/SSD 磁碟，確保建置過程穩定可靠。
• 提供 🇪🇺 歐洲 與 🇺🇸 美國 區域選擇。

節省您的時間：您只需幾分鐘即可連接第一個 GitLab Runner，立即開始執行 pipeline！

介紹

使用 Stackhero GitLab Runner 時，每個作業都會在全新容器中執行，採用 Docker executor。只要啟用 Docker-in-Docker（DinD），您就能直接在 pipeline 內建置自己的 Docker 映像檔。這種設定會在您的作業旁啟動一個 Docker daemon，因此您可以在 CI/CD 流程中執行 docker build 與 docker push 指令。

每次執行都享有 無限 CI/CD 分鐘數：您可以隨時進行建置，無需擔心使用量限制。您的 建置快取會儲存在 runner 專屬的磁碟上，這代表重複建置時可以重用先前的映像層，大幅縮短建置時間，讓 pipeline 執行更快速。

使用 Docker-in-Docker 建置 Docker 映像檔

您可以將以下 .gitlab-ci.yml 範例加入您的程式庫。這個設定會建置專案根目錄下的 Dockerfile：

build-image:
  stage: build
  image: docker:29
  services:
    - docker:29-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  before_script:
    - docker info
  script:
    # 將 "my-image" 替換為您想要的名稱：
    - docker build -t my-image .
    # 可選：對建置完成的映像檔進行快速測試：
    # - docker run --rm my-image /path/to/tests

我們在這個範例中使用 Docker 29 版映像檔。您可以根據需求選用更新的版本。最新標籤可參考 官方 Docker image 頁面。

在這個設定中，docker:29-dind 服務會啟動 Docker daemon。設定 DOCKER_TLS_CERTDIR: "/certs" 可讓您的作業與 Docker daemon 之間建立安全的 TLS 連線。

推送至 GitLab container registry

GitLab 提供預設變數（CI_REGISTRY、CI_REGISTRY_USER、CI_REGISTRY_PASSWORD、CI_REGISTRY_IMAGE），讓您的 pipeline 能安全地驗證並將映像檔推送到專案的 container registry，無需額外設定機密。

以下是一個建置並推送映像檔的作業範例：

build-and-push:
  stage: build
  image: docker:29
  services:
    - docker:29-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
  script:
    - docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
    - docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
    # 如果您在預設分支，也可以標記並推送 "latest"：
    - |
      if [ "$CI_COMMIT_BRANCH" = "$CI_DEFAULT_BRANCH" ]; then
        docker tag "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" "$CI_REGISTRY_IMAGE:latest"
        docker push "$CI_REGISTRY_IMAGE:latest"
      fi

若要將映像檔推送到其他 registry（如 Docker Hub 或私有 registry），您可以將認證資訊儲存為 CI/CD 變數，並以相同方式搭配 docker login 使用。

加速重複建置

您的 runner 磁碟會在 pipeline 之間保留，因此可以重複利用映像層作為建置快取，讓重複建置速度大幅提升。以下為範例設定：

build-cached:
  stage: build
  image: docker:29
  services:
    - docker:29-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
  script:
    # 先拉取最新映像檔以初始化快取（若存在）：
    - docker pull "$CI_REGISTRY_IMAGE:latest" || true
    - docker build --cache-from "$CI_REGISTRY_IMAGE:latest" -t "$CI_REGISTRY_IMAGE:latest" .
    - docker push "$CI_REGISTRY_IMAGE:latest"

這種方式可讓您的建置充分利用 Docker 層快取，只有新增或變更的層會被重建。

平行執行作業

您的方案會決定可同時執行的作業數量。相同階段的作業會一起啟動，最多同時執行到您的平行數上限。因此，多個獨立作業可以平行執行，最慢的作業完成時整個階段就會結束，而不需等待每個作業依序完成。

範例：

stages:
  - test

unit:
  stage: test
  image: node:22
  script: npm run test:unit

integration:
  stage: test
  image: node:22
  script: npm run test:integration

e2e:
  stage: test
  image: node:22
  script: npm run test:e2e

如果您將平行數設為 1 或更高，unit、integration 和 e2e 這三個作業會同時執行。

如需更多關於在 GitLab CI/CD pipeline 中建置 Docker 映像檔的資訊，請參考 官方 GitLab Docker build 文件。