如何在 Ubuntu 20.04 上設定 GitLab 持續整合 (CI) 流水線

每個開發人員都了解版本控制對軟體開發生命週期有多麼至關重要。它使多個人能夠同時在單個專案上工作，每個人都維護自己的程式碼副本，並選擇何時與團隊的其他成員共享。為了實現這一點，開發人員利用了 Git 儲存庫來協助進行版本控制。 GitLab 是一個基於 Web 的 Git 儲存庫，它不僅僅是一個版本控制工具。它還提供了 DevOps 工具、問題追蹤、持續整合和部署。

GitLab 提供了三種供您選擇的方案：GitLab 社群版 (CE)、GitLab 企業版 (EE) 和 GitLab SaaS。 GitLab CE 和 GitLab EE 是自我管理的解決方案。這意味著您可以自己下載、安裝和管理 GitLab 實例。GitLab SaaS 由 GitLab Inc. 託管。因此，您無需擔心安裝任何東西即可使用它。您只需要 建立 GitLab 帳戶 並開始使用。

在本教學中， 我們將向您展示如何使用 GitLab CI 設定持續整合管線，以監控您的儲存庫變更並執行自動化測試來驗證新程式碼。我們將首先設定一個 Git 儲存庫來託管程式碼。然後，我們將設定一個 CI 流程來監控對儲存庫的提交，並啟動一個 CI runner 在隔離的 Docker 容器中執行測試。

先決條件

首先，您需要一台執行 GitLab 版本控制軟體的伺服器。GitLab 自我管理版和 SaaS 版都可以執行自動化測試。然而，在免費的 SaaS 方案中，您的測試在時間（分鐘數）和資源方面會受到一些限制。如果您使用的是自我管理方案，您將擁有更大的自由度，因為您可以為您的 GitLab 實例分配任意多的資源。請按照我們關於 使用 GitLab 託管您自己的 Git 儲存庫 的教學，了解如何設定您自己的 GitLab 實例。

您將需要至少一台伺服器來用作 GitLab CI runner。但是，如果您願意，也可以擁有更多伺服器。如果您已設定了自我管理的 GitLab 實例，您可以使用同一台伺服器，但我們更傾向於為 CI runner 設定不同的伺服器。這篇關於 如何設定您的 Ubuntu 伺服器 的教學是一個很好的開始。

您需要在 GitLab CI runner 伺服器上安裝 Docker，以便在 Docker 容器中隔離測試環境。我們有一篇關於 如何在 Ubuntu 上安裝和操作 Docker 的教學可以幫助您完成此要求。

現在我們已經準備好了所需的一切，讓我們開始吧！

步驟 1：在 GitLab 實例上建立專案

我們將首先在 GitLab 上建立一個專案儲存庫。本教學將基於一個 Node.js 應用程式。由於我們不想從頭開始建立專案檔案，GitLab 提供了一個從其他版本控制儲存庫匯入專案的工具，我們將利用該工具。我們正在匯入的應用程式是一個簡單的「hello world」應用程式，使用 Express.js – 一個適用於 Node.js 應用程式的極簡 Web 框架 建置。我們將使用 Mocha 和 Chai – 這些是用於單元測試的 JavaScript 框架。Mocha 支援非同步測試、測試覆蓋率報告，並可與其他斷言庫搭配使用。Chai 是一個斷言庫。它可以與任何測試框架搭配使用，在我們的案例中，我們將把 Mocha 與 Chai 搭配使用。

現在您已了解我們專案的基本資訊，請登入您的 GitLab 實例（無論是自我管理版還是 SaaS 版），點擊頂部導覽列上的 ‘加號’ 圖示，然後選擇「New project」。或者，如果您捲動到帳戶首頁的頂部，可以點擊「New project」按鈕：

在新專案頁面上，點擊 Import project 標籤頁：

接下來，在開啟的頁面中，點擊 Repo by URL 按鈕：

雖然有 GitHub 匯入選項，但我們不打算使用它，因為它需要個人存取權杖 (Personal access token)。由於我們使用的是公開儲存庫，因此不需要設定個人存取權杖，而且僅使用 URL 進行匯入非常簡單。

之後，複製以下 URL 並將其貼上到 Git Repository URL 欄位中：

它看起來應該像這樣：

將儲存庫保持為 Private 並在完成後按一下 Create project 按鈕。等待幾秒鐘讓專案從 GitHub 匯入，它就會出現在您的 GitLab 儲存庫中。GitLab 會以與 GitHub 儲存庫專案相同的詳細資訊匯入該專案。

步驟 2：分析 .gitlab-ci.yml 檔案

GitLab CI 會掃描 GitLab 上的每個儲存庫，以尋找名為 .gitlab-ci.yml 的檔案，以了解它應該如何執行自動化測試。在我們剛剛匯入的儲存庫中，您可以在專案檔案中看到一個 .gitlab-ci.yml 檔案。您可以在他們官方的 yml 上找到更多關於 GitLab CI .gitlab-ci.yml 檔案文件關鍵字參考.

在 GitLab 儲存庫介面中，按一下 .gitlab-ci.yml 檔案以在瀏覽器頁面中開啟它。它看起來應該像這樣：

請注意行縮排。該檔案遵循嚴格的 GitLab CI YAML 設定語法，以在特定條件下按指定順序定義要執行的各種操作。為了確保您的設定檔正確，GitLab 提供了一個用於驗證的測試公用程式。在您的 GitLab 執行個體中，在您的專案儲存庫中，您可以造訪 CI lint 介面來驗證您的 .gitlab-ci.yml。按一下左側導覽功能表上的 CI/CD，然後在出現的頁面中按一下 CI lint 按鈕：

設定檔中的指令將在下方討論。

• 基礎 Docker 映像檔

設定檔中的第一行宣告了應該用於執行測試的 Docker 映像檔。由於我們正在建置 Node.js 應用程式，我們將使用最新的 Node.js 映像檔：

• 階段

然後，我們定義希望持續整合測試通過的不同階段。我們只有兩個階段：

在定義階段名稱時，像 build 或 test 這樣的名稱是隨機選擇的 – 您可以選擇任何您喜歡的名稱。但是，您必須正確排序階段，因為這決定了執行的流程。在我們的案例中，build 階段中的工作會在 test 階段。GitLab runner 將平行執行同一階段中的工作，並在等待所有工作完成後，才開始執行下一階段中的工作。

• 快取

包含一個 cache 定義，以指定在工作執行之間將快取或儲存以供稍後使用的檔案和目錄：

定義快取有助於縮短執行依賴於在執行之間不太可能變更的資源的工作所需的時間。我們指定要快取的 node_modules 目錄。這是 npm 安裝專案依賴項的目錄。

• 工作

我們在設定中有兩個工作：

• install_dependencies

命名工作時，您可以自由選擇任何名稱。但是，建議使用具描述性的名稱，因為它們會用於 GitLab UI 中 – 這在偵錯期間會很有幫助。您會發現網路上大多數設定都結合了 npm install 與測試階段中的指令。我們只是將它們分開，以幫助演示工作是如何互動的，因為這是一個相當小的專案。而 stage 指令將此工作標記為 build – 它在 build stage.

而 script 指令指定了在此工作執行中要運行的指令。您可以透過在 script 區塊中新增行來指定多個指令。當然，您需要注意正確的縮排，並記住腳本應該執行的順序。

而 artifacts 指令指定了要在階段之間儲存和共享的檔案或目錄路徑。再次提醒，正確安排階段的順序對於確保其他檔案擁有執行所需的內容至關重要。而 npm install 指令將會安裝依賴項到 node_modules 目錄中。透過在 artifacts 中宣告它，我們使其可用於後續階段中執行的工作。如果您想下載這些檔案，也可以在 GitLab UI 中取得。

• test_with_mocha

此工作是在 test 階段運行。由於此工作是在 build 階段的工作運行之後運行的，因此在 build 階段中宣告的產物（即我們應用程式的依賴項）將可用於 test 階段。script 區塊指定了要運行我們測試的 npm 指令。我們首先啟動應用程式，然後對該應用程式運行測試。運行這些指令會觸發在 package.json 腳本區塊部分中指定的指令：
至此，您應該對 .gitlab-ci.yml 檔案有了基本的了解。我們說是基本的，因為這只是一個靜態的 hello world 應用程式。接下來，讓我們看看如何觸發新的 CI 運行。

步驟 3：觸發 GitLab CI 運行

您會很高興知道，一旦您的儲存庫中有了 .gitlab-ci.yml 檔案，您推送至其中的任何新提交都將觸發新的持續整合運行。對於自行管理的 GitLab 實例，如果您尚未設定 GitLab runner，CI 運行將會被設為「pending」（待處理）。

GitLab SaaS 為使用者提供了一些共享的 runner，可以自動接取並執行他們的工作。這只有在共享 runner 有空閒且您未超出配額的情況下才有可能。在 GitLab SaaS 中，您可以透過前往專案的 shared runners 頁面來選擇是否要讓您的儲存庫使用 Settings > CI / CD 頁面，如下圖螢幕截圖所示。在此頁面中，您還將找到有關 GitLab runner 安裝說明的資訊，我們將在下一步中深入探討：

現在，讓我們做一個小修改來觸發 CI 運行。導覽回您的 node_pipeline GitLab 專案儲存庫：

點擊上方醒目顯示的 README.md 檔案以進行檢視：

點擊 ‘Edit’ 按鈕以在瀏覽器中開啟檔案進行編輯，並新增一些文字：

新增文字後，向下捲動並點擊 Commit changes 按鈕以儲存變更。您可以根據需要修改提交訊息。當流水線運行時，它將作為標題顯示在 GitLab UI 中。我們將其保留為 Update README.md ，因為這相當具有描述性：

提交變更後，返回專案主頁。您會注意到最近一次提交旁有一個小的 paused icon 。如果您將滑鼠懸停在該圖示上，它將顯示： ‘Pipeline:pending’:

這意味著 CI 運行已被觸發。然而，測試尚未運行。在左側的導覽選單中，點擊 CI/CD, 然後選擇 Pipelines. 這將開啟一個顯示有關流水線更多詳細資訊的頁面。您可以看到 CI 處於 pending 狀態，並被標記為 stuck：

要獲取有關運行的更多詳細資訊，請點擊 pending 狀態。您將看到下方的檢視，其中顯示了運行的不同階段，以及與每個階段連結的個別工作：

您也可以點擊個別工作以查看其更詳細的資訊，例如導致延遲的原因。在執行失敗的情況下，您可以在此處查看導致工作失敗的原因：

該訊息表示工作已卡住，因為您尚未設定任何可以執行此工作的活動執行器（runner）。我們將在下一步中進行此設定。當您啟用執行器時，工作將自動開始執行。當工作執行時，您將在此介面上看到輸出，以及在工作執行時產生的其他可下載產物（artifacts）。

步驟 4：設定 GitLab CI Runner 服務

現在是時候使用我們在「先決條件」章節中聲明的第二台伺服器了。我們將在此伺服器上安裝並設定 GitLab runner 服務。您可以部署該服務，以便為 GitLab 上的不同專案執行多個 runner 執行個體。

您可以選擇將 runner 部署在託管自管 GitLab 執行個體的同一台伺服器上。然而，為了確保執行個體不受資源限制，最好設定一個獨立的 CI runner 執行個體。無論您選擇哪種配置，都必須安裝 Docker以隔離測試環境。

安裝 GitLab CI runner 的過程與安裝自管 GitLab執行個體的過程類似。我們首先使用以下命令下載指令碼，將官方 GitLab 儲存庫新增至 apt 來源：

系統提示時請提供您的 root 密碼。接下來，您現在可以執行命令來安裝最新的 GitLab CI runner：

上述命令會安裝並註冊一個 runner 服務，供您的專案使用。

步驟 5：獲取註冊權杖並連結 GitLab Runner

要設定 GitLab CI runner 以開始接受工作，您需要一個 GitLab runner 權杖。runner 需要使用它來向您的 GitLab 伺服器執行個體進行驗證。根據您想如何使用 runner，有兩種權杖類型：專案專用（project-specific） 與 共享 runner（shared runner）。

專案專用 runner 適用於您對 runner 有獨特需求的情況。例如，如果您的 gitlab-ci.yml 中含有帶有獨特權杖的部署定義，則可能建議使用特定的 runner 以正確驗證到部署環境中。另一個考量是您的持續整合階段是否包含資源密集型程序。若是如此，使用專案專用 runner 將是理想的選擇。請注意，專案專用 runner 不會接受來自其他專案的工作。

共享 runner 是通用型的，可供多個專案使用。託管於 GitLab Inc 的 GitLab SaaS 執行個體擁有一些共享 runner，它們會自動接手您的管線，如 步驟三 中所述。Runner 會根據一項演算法從您的配置中獲取工作，該演算法會考量每個專案目前正在執行的工作數量。共享 runner 比專用 runner 更具彈性。它可以從 GitLab 執行個體的管理員帳戶進行設定。讓我們來看看如何獲取這兩種 runner 的權杖。

• 註冊專案專用 Runner

要註冊專案專用 runner，請在您的 GitLab 執行個體或 GitLab SaaS 帳戶中開啟您的專案。從左側的導覽功能表中，點擊 Settings 項目並選擇 CI/CD 選項：

之後，向下滾動到 Runners 區段，然後點擊按鈕以展開該區段：

左側說明了如何註冊專案專用 runner。這是 GitLab SaaS 執行個體的檢視畫面。您也可以使用 Kubernetes 設定自動 runner，但在本教學中我們將使用手動 runner：

接下來，您需要關注為此專案提供權杖的區段。對於自我託管的 GitLab 實例，該 URL 將顯示執行您的 GitLab 實例的伺服器網域：

您可以透過切換右側區段下方的開關來停用此專案的共享 Runner：共享 Runner。 然後，將顯示的註冊權杖複製到您的記事本中，因為我們稍後會用到它。

• 註冊共享 Runner

要註冊共享 Runner，您需要以管理員身份登入您的自我託管 GitLab 實例。要存取管理控制台，請按一下 扳手 圖示（位於頂部導覽功能表中）：

在 管理控制台 中，按一下 Runners （位於左側功能表的 概覽 區段）。這將開啟一個包含 共享 Runner 設定說明之頁面：

複製右側顯示的註冊權杖，位於 手動設定共享 Runner 下方。您將在下一步中使用該權杖來註冊 Runner。

• 將 GitLab CI Runner 與 GitLab 實例連結

在此步驟中，您將把 GitLab 實例與 CI Runner 連結。重新登入您在 步驟四 中安裝 GitLab Runner 服務的伺服器。要開始 Runner 註冊程序，請在終端機中輸入以下指令：

該指令會提示您回答一系列問題：

• 輸入 GitLab 實例 URL（例如，https://gitlab.com/）：

使用 https:// 來指定 SSL 以提供您的 GitLab 實例網域名稱。

• 輸入註冊權杖：

提供您的註冊權杖。您將在此處選擇要讓此 Runner 成為專案專用還是共享。您只能為其中一個選項提供您之前複製的其中一個權杖。

• 輸入 Runner 的描述：

為您的 CI Runner 選擇一個具描述性的名稱，因為它將顯示在 GitLab 實例的使用者介面上。

• 輸入執行程式（executor）：custom, docker-ssh, parallels, virtualbox, docker, shell, ssh, docker+machine, docker-ssh+machine, kubernetes：

在此處，它為您提供了選擇執行程式來執行任務的選項。輸入 Docker.

• 輸入 Runner 的標籤（以逗號分隔）：

這是選填的。您可以輸入任何標籤名稱，例如此 Runner 包含的相依性。您現在可以先留空。

• 輸入預設的 Docker 映像檔（例如，ruby:2.6）：

在此處，您需要指定一個用於執行任務的預設通用映像檔，以防 gitlab-ci.yml 檔案未指定映像檔。輸入 alpine:latest ，因為它是一個體積小、通用且安全的映像檔。按下 Enter 鍵，Runner 將自動註冊並啟動：

要檢視目前可用的 Runner 清單，請輸入以下指令：

步驟 6：確認 CI Runner 已成功連結至 GitLab

接下來，返回瀏覽器並造訪 GitLab 實例中的專案頁面。根據您註冊 Runner 後經過的分鐘數，您可能會看到任務目前正在執行：

或者它可能已經完成：

之後，導覽至 Pipelines 頁面，可以透過左側功能表 CI/CD > Pipelines ，或者按一下 running, passed, 或 failed 圖示（如果管線遇到錯誤）以檢視 CI 執行的狀態。在這裡我們可以看到其中一個階段（建置階段）已通過，而另一個仍在執行中：

在表格中，於 Stages 標題下，按一下其中一個階段圖示以檢視相關聯的任務：

然後，按一下快顯視窗中的任務以檢視詳細資訊：

任務已執行，您可以在 npm 指令正在安裝相依性時檢視進度。在右側，您可以檢視其他相關資訊。您可以選擇下載該任務的產物（artifacts）。您也可以從下拉式選單中在不同階段之間切換以檢視其他任務。

在這裡，您可以檢視當您在測試階段中選取任務時顯示的測試案例：

可用的 Runner

在左側功能表中，如果您按一下 Settings > CI/CD ，並展開 Runners 區段，您應該會看到剛剛註冊的 Runner。根據您指定的是專案專用權杖還是共享權杖，該 Runner 將分別顯示在對應的區段中。

在這裡您可以看到我們註冊了一個專案專用權杖。該 Runner 顯示在 Specific Runners:

結論

在本教學中，您學習了如何使用 GitLab CI 自動化測試。我們首先在 GitLab 上建立了一個 Node.js 應用程式專案。該專案包含了一些測試案例和一個 gitlab-ci.yml。我們了解到 GitLab 使用 gitlab-ci.yml 檔案來決定觸發時要執行的操作。一個 gitlab-ci.yml 檔案只是一個設定檔，其中包含建置和測試應用程式的指令，以 YAML 格式編寫，以便 GitLab CI Runner 能夠理解。

我們還成功在獨立的主機上設定了 GitLab CI Runner。我們註冊了它，以便在有觸發時從我們的 GitLab 執行個體中取得工作。雖然這是一個簡單的專案，但您可以以此資訊為基礎，為複雜的專案設定管線。將專案新增至 GitLab 以及連結 GitLab CI Runner 的步驟是相同的。改變的是 gitlab-ci.yml 檔案中的指令和階段。

祝您運算愉快！