GitLab Runner: 建立 Docker 映像檔

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

👋 歡迎瀏覽 Stackhero 文件！

Stackhero 提供簡單易用的 GitLab Runner cloud 方案，讓您高效且輕鬆地執行 GitLab CI/CD 任務。您可以享有以下優勢：

無限 CI/CD 分鐘數：隨時隨地運行 pipeline，無需按分鐘計費，亦無額外收費。

多個並行任務：可同時運行多個 job，加快開發流程。

支援 Docker executor 及 Docker-in-Docker：輕鬆於 CI/CD 流程中建構及推送 container image。

完美兼容 GitLab.com 及 自建 GitLab 實例。

專屬私人基礎設施，配備高速 NVMe/SSD 儲存，確保建構效能穩定且可預測。

服務覆蓋 🇪🇺 歐洲 及 🇺🇸 美國 地區，靈活配合您的團隊需求。

節省時間：您只需數分鐘即可連接首個 GitLab Runner，立即開始運行 pipeline！

簡介

使用 Stackhero GitLab Runner，每個 job 都會在一個全新的 container 內執行，並採用 Docker executor。只要啟用 Docker-in-Docker（DinD），您就可以直接在 pipeline 內建構自己的 Docker 映像檔。這個設定會在您的 job 旁邊啟動一個 Docker daemon，讓您可以在 CI/CD 流程中執行 docker build 和 docker push 指令。

每次執行都享有 無限 CI/CD 分鐘：您可以隨時進行建構，無需擔心用量限制。您的 build cache 會儲存在 runner 專屬的硬碟上，因此重複建構時可以重用之前的 layer，大幅縮短建構時間，加快 pipeline 完成速度。

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

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

build-image:
  stage: build
  image: docker:29
  services:
    - name: docker:29-dind
      alias: docker
  variables:
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
  before_script:
    - docker info
  script:
    # 請將 "my-image" 替換為您想要的名稱：
    - docker build -t my-image .
    # 如有需要，可對建構好的映像檔進行快速測試：
    # - docker run --rm my-image /path/to/tests

本範例使用 Docker image 版本 29。您可以根據需要選用更新的版本。最新的 tag 可參考官方 Docker image 頁面。

在這個設定中，docker:29-dind 服務會在您的 job 旁啟動一個 Docker daemon，而 DOCKER_HOST: "tcp://docker:2375" 則告訴 docker CLI 使用這個 daemon。當您宣告 docker:dind 服務時，務必設定 DOCKER_HOST： 否則 CLI 會默默連接到其他 daemon，導致即使服務設定錯誤，build 也可能通過，這會隱藏真正的問題（並導致像 Testcontainers 這類依賴該服務的工具失效）。DOCKER_TLS_CERTDIR: "" 代表透過內部 job 網絡上的非 TLS 2375 port 連線。

如果想要更簡單的方式，您可以省略 services 區塊及上述兩個變數：Stackhero 的 runner 也會透過掛載的 socket 提供一個可用的 Docker daemon，因此只需執行 docker build，無需額外設定。

使用 Testcontainers 執行測試

Testcontainers 是一個測試函式庫，支援 Java、Go、Node.js、Python、.NET 等語言，能在測試期間以臨時 Docker container 啟動真實服務。您的整合測試不需模擬資料庫或 message broker，而是直接連接到真正的 PostgreSQL、MySQL、Redis 或 Kafka 實例，測試前建立、測試後自動移除。這在 Java 及 Spring 專案中特別受歡迎。

Testcontainers 需要 Docker daemon，因此可直接採用上述 Docker-in-Docker 設定，無需額外變數：

test:
  stage: test
  # 請使用測試所需的 image（此處為 JDK），不一定要用 docker image：
  image: gradle:jdk21
  services:
    - name: docker:29-dind
      alias: docker
  variables:
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
  script:
    - gradle test

Testcontainers 會讀取 DOCKER_HOST 來尋找 daemon，並重用 docker 這個 hostname 來連接它啟動的 container 所開放的 port。這兩者都能正常運作，因為 docker alias 會在您的 job 網絡上解析。

請務必在 Testcontainers 的 job 中保留 DOCKER_HOST。若未設定，Testcontainers 會退回 runner 掛載的 Docker socket，然後嘗試用 host IP 連接您的測試 container，但 job 並無法連線。常見症狀包括 Ryuk helper container 出現 Wait strategy failed. Container is removed 或 Timed out waiting for log output matching '.*Started.*'。

推送映像檔到 GitLab container registry

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

以下是一個建構並推送映像檔的 job 範例：

build-and-push:
  stage: build
  image: docker:29
  services:
    - name: docker:29-dind
      alias: docker
  variables:
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
  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 之間保留，因此可以重用映像檔 layer 作為 build cache，讓重複建構更快速。以下為範例設定：

build-cached:
  stage: build
  image: docker:29
  services:
    - name: docker:29-dind
      alias: docker
  variables:
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
  script:
    # 先拉取最新映像檔以初始化 cache（如有）：
    - 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"

這種方式可讓您的 build 充分利用 Docker 的 layer cache，只有新增或變更的 layer 會被重建。

並行執行 job

您的方案會決定可同時執行多少個 job。同一個 stage 的 job 會一起啟動，最多可達您的並行上限。這代表多個獨立的 job 可以同時執行，最慢的 job 完成後整個 stage 就會結束，而不需逐一等待。

範例：

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 這三個 job 會同時執行。

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