在 WSL 2 上使用 Docker 部署 GitLab Runner

當 GitLab 主服務已經跑在 Windows 上，下一步通常就是補一台能執行 Linux job 的 Runner。把 Runner 放進 WSL 2 的 Docker 裡，成本低、維護簡單，也很接近 GitLab 官方文件的標準做法。

不過這個架構也有一個代價要先講清楚。GitLab 官方在 Docker 版 Runner 文件裡提到，把 /var/run/docker.sock 掛進 Runner 容器後，等於把 Docker Daemon 的完整控制權交給它，隔離保證會跟著下降。請參考：Run GitLab Runner in a container。

如果這台 Runner 是拿來跑個人專案、小型團隊或內網 CI，這個取捨通常可以接受；但如果是多人共用或安全要求高的環境，還是應該把 Runner 佈署在更獨立的 Linux 主機上。

先建立 Runner 容器

GitLab 官方給的容器版安裝方式很直接，我們先建立一個永久 volume 保存設定，再啟動 Runner 容器。

在 WSL 2 終端機執行：

1docker volume create gitlab-runner-config

接著啟動 Runner：

1docker run -d --name gitlab-runner --restart always \
2  -v /var/run/docker.sock:/var/run/docker.sock \
3  -v gitlab-runner-config:/etc/gitlab-runner \
4  gitlab/gitlab-runner:latest

這個設定的重點只有兩個：

1. gitlab-runner-config 會保存 config.toml，容器重建後設定不會消失
2. /var/run/docker.sock 讓 Runner 可以用 Docker executor 幫 job 再起其他容器

如果我們沒有把 docker.sock 掛進去，容器內的 Runner 雖然能啟動，卻沒辦法真的替 pipeline 建立 Docker job。

在 GitLab 建立新的 Runner

GitLab 已經把舊式 registration token 標成 deprecated，GitLab 20.0 預計會移除；現在應該先在 GitLab UI 建立 Runner，再用 runner authentication token 註冊，也就是那串 glrt-...。請參考：Registering runners 與 Manage runners。

如果你用的是 GitLab Self-Managed，可以到：

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

如果只想讓某個專案使用，則到：

Project > Settings > CI/CD > Runners

建立完成後，先把畫面上顯示的 authentication token 記下來。這段 token 不會一直公開擺著，拖太久再回來通常就得重新建立。

用 Docker executor 註冊

Runner 容器起來後，直接用一個短生命週期的 gitlab-runner 容器寫入設定最乾淨。GitLab 官方文件現在也是這樣示範的。

執行：

1docker run --rm -it \
2  -v gitlab-runner-config:/etc/gitlab-runner \
3  gitlab/gitlab-runner:latest register

註冊過程中會一路問下列欄位：

1. GitLab instance URL：例如 http://gitlab.my.tw
2. runner authentication token：貼上 glrt-...
3. description：例如 wsl2-docker-runner
4. job tags：建議填 linux,docker
5. maintenance note：可留空
6. executor：輸入 docker
7. default Docker image：先填 alpine:latest 就夠用

如果你之後主要跑 Ubuntu-based job，也可以在這裡改成別的預設 image，但沒有特殊需求時，先用一個乾淨、輕量的基底最省事。

先確認 Runner 真的能接 job

註冊完成後，回 GitLab 的 Runners 頁面，狀態應該會變成 Online。這還不算真的完成，我比較建議立刻丟一個最小測試 job：

1smoke-test:
2  tags:
3    - linux
4    - docker
5  image: alpine:latest
6  script:
7    - echo "runner is ready"

這種測試有一個好處：它會立刻把 tag、executor、容器啟動和網路問題一次跑過。若哪裡有漏，當下就能知道，而不是等正式 pipeline 上線才發現 Runner 只是看起來在線。

若想直接從主機看 Runner log，也可以執行：

1docker logs gitlab-runner

總結

把 GitLab Runner 放進 WSL 2 的 Docker 裡，對個人實驗或小型團隊來說，確實是最順手的 Linux CI 入口。設定量不大，更新也單純，搭配 GitLab 新的 Runner 建立流程之後，整個註冊步驟比舊版清楚很多。

這台 Runner 很適合接 Linux 容器建置、單元測試與一般自動化流程；如果 job 要碰 Windows SDK、桌面應用程式或 PowerShell，本機 Windows Runner 仍然是更合理的選擇。

作者

Ted Liou

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

GitHub