本文介紹如何在 GitLab 上配置 CI 流水線。我在前面的文章中介紹了 基于 CMake 和 VSCodium 的構建系統 和 基于 GoogleTest 和 CTest 的單元測試。本文將在此基礎上進一步配置 CI 流水線。我會先演示如何布設和運行 CI 流水線，然后再介紹如何配置它。

CI 是指提交到代碼倉庫的代碼變更會被自動構建和測試。在開源領域，GitLab 是一個流行的 CI 流水線平臺。除了作為中心 Git 倉庫外，GitLab 還提供 CI/CD 流水線、問題跟蹤issue tracking 和 容器注冊表container registry功能。

相關術語

在進入正題之前，我先介紹在本文和 GitLab 文檔 中會遇到的常見術語。

• 持續交付continuous delivery（CD）：自動化供應軟件，以供隨時交付
• 持續部署continuous deployment（CD）：自動化軟件發布
• 流水線pipeline: CI/CD 的直接構件，它由階段和作業構成
• 階段stage：一組作業
• 作業job：某項需要執行的具體任務，比如編譯、單元測試等
• 執行器runner：實際執行作業的服務

布設 CI 流水線

在下面的章節中，我將復用以前的 示例工程。點擊 GitLab 倉庫頁面右上角的 復刻Fork

Fork the project

設置執行器

為了讓你對整個流程有所了解，我們先從在本地安裝執行器講起。

參照執行器服務 安裝指南 安裝好服務，然后注冊執行器。

1、選擇 GitLab 項目頁面左側的 設置Settings，再選擇 CI/CD。

Select CI/CD in Settings

2、展開 執行器Runners 區域，關閉 共享的執行器Shared runners

Configure runner

3、在終端中運行 gitlab-runner register，根據提示輸入以下注冊信息：

• GitLab 實例: https://gitlab.com/ （如上圖）
• 注冊令牌：從執行器區域中獲取 （如上圖）
• 描述：按需自由填寫
• 標簽：可以不填
• 執行環境：選 Shell

如果有需要，你可以在 ~/.gitlab-runner/config.toml 中修改這些配置。

4、用命令 gitlab-runner run 啟動執行器。你可以在 GitLab 的項目設置界面執行器區域看到執行器的狀態：

Available specific runners

運行流水線

前面已經提過，流水線就是一組由執行器執行的作業。每個推送到 GitLab 的提交都會生成一個附加到該提交的流水線。如果多個提交被一起推送，那么只會為最后一個提交生成流水線。為了演示，我直接在 GitLab 在線編輯器中提交和推送修改。

打開 README.md 文件，添加一行數據：

Web editor

現在提交修改。

這里注意默認的行為是為提交新建一個分支，為了簡便起見，我們擇提交到主分支。

Commit changes

提交后一會兒后，你就應該改能看到 GitLab 執行器執行的控制臺中有輸出消息：

Checking for jobs... received job=1975932998 repo_url=<https://gitlab.com/hANSIc99/cpp\_testing\_sample.git> runner=Z7MyQsA6
Job succeeded duration_s=3.866619798 job=1975932998 project=32818130 runner=Z7MyQsA6

在 GitLab 項目概覽界面左側選擇 CI/CD --> 管道Pipelines，查看最近執行的流水線：

Pipeline overview

選中流水線可以在詳情界面看到哪些作業失敗了，并能查看各個作業的輸出。

當遇到非零返回值是就認為作業執行失敗了。在下面的例子中我通過調用 exit 1 強制讓作業執行失敗：

Job overview

CI 配置

階段、流水線和作業的配置都在倉庫根目錄的 .gitlab-ci.yml 文件中。我建議使用 GitLab 內置的流水線編輯器，它會自動對配置進行檢查。

stages:
- build
- test
build:
  stage: build
  script:
    - cmake -B build -S .
    - cmake --build build --target Producer
  artifacts:
    paths:
      - build/Producer
RunGTest:
  stage: test
  script:
    - cmake -B build -S .
    - cmake --build build --target GeneratorTest
    - build/Generator/GeneratorTest
RunCTest:
  stage: test
  script:
    - cmake -B build -S .
    - cd build
    - ctest --output-on-failure -j6

文件中定義了兩個階段：build 和 test，以及三個作業：build、RunGTest 和 RunCTest。其中作業 build 屬于一個同名的階段，另外兩個作業屬于階段 test。

script 小節下的命令就是一般的 Shell 命令。你可以認為是將它們逐行輸入到 Shell 中。

我要特別提及 產物artifact 這個特性。在示例中我定義了二進制的 Producer 為作業 build 的產物。產物會被上傳到 GitLab 服務器，并且可以從服務器的這個頁面上被下載：

Pipeline artifacts

默認情況下，后續階段的作業會自動下載先前階段作業生成的所有產物。

你可以在 docs.gitlab.com 上查看 gitlab-ci.yml 參考指南。

總結

上面只是一個最基本的例子，讓你對持續集成的一般原則有一個了解。再演示中我禁用了共享執行器，然而這才是 GitLab 的優勢所在。你可以在一個干凈的容器化的環境中構架、測試和部署程序。除了使用 GitLab 提供的免費執行器，你也可以用自己的容器作為執行器。當然還有更高階的用法：用 Kubernetes 來協調調度執行者容器，讓流水線適應大規模使用的使用場景。如需進一步了解，可以查看 about.gitlab.com。

如果你使用的是 Fedora，需要注意的一點是目前 GitLab 執行者還不支持用 Podman 作為容器引擎。（LCTT 譯注：Podman 是 Fedora 自帶的容器引擎。）根據 議題issue #27119，對 Podman 支持已將列上日程。（LCTT 譯注：Podman 4.2 及以上版本增加了對于 GitLab 執行器的支持。）

把重復性的操作描述成作業，并將作業合并成流水線和階段，可以讓你跟蹤它們的質量而不增加額外工作。。特別是在大型社區項目中，適當配置的 CI 可以告訴你提交的代碼是否對項目有改善，為你接受或拒絕合并請求提供依據。