GitLab Runner: 建立 Docker 映像檔

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

👋 歡迎來到 Stackhero 文件中心！

Stackhero 提供簡單易用的 GitLab Runner 雲端解決方案，讓您高效且無煩惱地執行 GitLab CI/CD 任務。您可以期待以下功能：

無限 CI/CD 時數：隨時運行您的 pipeline，無需擔心按分鐘計費或額外費用。

多個任務同時執行：可同時平行運行多個任務，加速您的開發流程。

支援 Docker executor 及 Docker-in-Docker：輕鬆在 CI/CD 流程中建置並推送容器映像檔。

完美支援 GitLab.com 及 自建 GitLab 實例。

專屬私有基礎架構，搭配高速 NVMe/SSD 儲存，確保建置效能穩定且可預期。

提供 🇪🇺 歐洲 與 🇺🇸 美國 區域，滿足您團隊的需求。

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

介紹

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

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

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

您可以將以下範例 .gitlab-ci.yml 加入您的程式庫。這個設定會建置專案根目錄下的 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 29 版映像檔。您可以根據需求選擇更新版本。最新標籤可參考官方 Docker image 頁面。

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

作為更簡單的替代方案，您可以省略 services 區塊與上述兩個變數：Stackhero 的 runner 也會透過掛載的 socket 提供可用的 Docker daemon，因此只需執行 docker build，無需額外設定即可運作。

使用 Testcontainers 執行測試

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

Testcontainers 需要 Docker daemon，因此與上述 Docker-in-Docker 設定完全相同，無需額外變數：

test:
  stage: test
  # 請使用測試所需的映像檔（此處為 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 主機名稱來存取其啟動容器所開放的 port。兩者都能正常運作，因為 docker 別名會在作業網路中解析。

請在 Testcontainers 作業中保留 DOCKER_HOST。若未設定，Testcontainers 會退回 runner 掛載的 Docker socket，接著嘗試連線到主機 IP 上的測試容器，但作業無法連線。常見症狀為 Ryuk 輔助容器出現 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，無需額外機密。

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

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 之間保留，讓您能將映像檔層作為建置快取重複利用，顯著加快重複建置速度。以下為範例設定：

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:
    # 先拉取最新映像檔以初始化快取（若存在）：
    - 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 文件。