在 Windows 上直接部署 GitLab Runner

只要 CI 工作會直接碰 Windows 環境，例如 .NET Framework、MSBuild、PowerShell 腳本、簽章工具或某些只能裝在 Windows 的 SDK，把 GitLab Runner 直接裝在 Windows 主機上，通常還是最省事的做法。少了一層容器隔離，換來的是相依套件不用繞路，排錯也直接很多。

GitLab 官方對 Runner 的建議，是盡量裝在和 GitLab 主服務分開的機器上，這樣安全性與效能都比較好。請參考：Install GitLab Runner。如果我們只是個人實驗室或小型內網，先把它裝在同一台 Windows 主機上也可以，但要知道這是方便優先，不是標準答案。

這種 Runner 適合哪些工作

Windows Runner 最適合處理這幾類任務：

1. 需要 Windows 檔案系統或登錄表的腳本
2. 需要 Visual Studio Build Tools、.NET Framework 或 IIS 元件的建置流程
3. 需要 PowerShell 直接操作本機服務、憑證或安裝程式的工作

如果 pipeline 只是單純做 Linux 容器建置，Windows Runner 反而不是最划算的選擇。那種情況把 Runner 放去 WSL 2 或原生 Linux 會比較乾淨。

下載執行檔並準備目錄

先建立一個專門放 Runner 的目錄，例如 C:\GitLab-Runner。GitLab 官方文件現在還多提醒了一件事：這個資料夾和 gitlab-runner.exe 最好限制寫入權限，避免一般使用者替換執行檔，讓服務以高權限執行惡意程式。請參考：Install GitLab Runner on Windows。

接著下載 Windows x64 版執行檔，重新命名成 gitlab-runner.exe，放進 C:\GitLab-Runner。

還有一個很容易被忽略的小地方。GitLab 官方目前仍提到，Windows 系統地區若不是 English (United States)，有機會碰到字元編碼問題。這不是每台機器都會中，但真的遇到時很浪費時間，所以這裡先記一下。

先在 GitLab 建立 Runner，再回來註冊

GitLab 現在主推的是新的 Runner 建立流程，不再建議沿用舊的 registration token。官方文件已經明寫，runner registration token 屬於 deprecated 流程，預計會在 GitLab 20.0 移除；現在應該使用 runner authentication token，也就是常見的 glrt-...。請參考：Registering runners 與 Manage runners。

如果你是 GitLab Self-Managed 管理者，可以到：

Admin area > CI/CD > Runners > Create instance runner

如果是單一專案要用，則到：

Project > Settings > CI/CD > Runners

或群組層級的：

Group > Build > Runners

建立完成後，GitLab 會顯示註冊流程，並在畫面上短暫提供 runner authentication token。這段 token 要先抄下來，離開頁面後就不會一直掛在那裡等我們。

用 Shell executor 註冊 Windows Runner

以系統管理員身分開啟 PowerShell，切到 Runner 目錄：

1cd C:\GitLab-Runner

先執行註冊：

1.\gitlab-runner.exe register

註冊過程中會依序問幾個欄位：

1. GitLab instance URL：輸入你的 GitLab 網址，例如 http://gitlab.my.tw
2. runner authentication token：貼上剛剛建立 Runner 時拿到的 glrt-...
3. description：輸入好辨識的名稱，例如 windows-shell-runner
4. job tags：建議填 windows,powershell
5. maintenance note：可留空
6. executor：輸入 shell

完成註冊後，再把它安裝成 Windows 服務並啟動：

1.\gitlab-runner.exe install
2.\gitlab-runner.exe start

如果這台機器有 PowerShell 7，GitLab Runner 在 Windows 上預設會使用 pwsh。若你想改回 Windows PowerShell，之後可以再調整 C:\GitLab-Runner\config.toml 裡的 shell 設定。

註冊後先檢查兩件事

第一，回到 GitLab 的 Runners 頁面，確認這台 Runner 已經顯示為 Online。

第二，直接看一下 Windows 服務有沒有正常起來。如果想用命令列確認 log，GitLab 官方提供的是 Windows Event Log：

1Get-WinEvent -ProviderName gitlab-runner

看到服務啟動訊息後，再丟一個最小的 pipeline 測一次會比較穩。只要 shell executor 真正開始跑 job，我們就能很快知道本機缺哪些 SDK、PATH 或權限。

總結

Windows Runner 的價值很明確：當 CI 任務離不開 Windows 環境時，它比硬把流程塞進容器裡實際得多。這種做法的代價是隔離性較弱，也更依賴主機本身的工具鏈整潔度，所以最好把用途收斂清楚，不要什麼 job 都丟進來。

如果本文這台 Runner 主要負責 .NET、PowerShell 或 Windows 專屬工具，那它會很好用；若是純 Linux 容器工作，還是把 Runner 放到 WSL 2 或原生 Linux 會比較合理。

作者

Ted Liou

現職 Unity C# 工程師，主要分享 Unity、C# 與 Vibe Coding 相關技術教學。

GitHub