GitLab Runner config.toml 設定與常用 CI/CD 變數

Mon, 26 Oct 2026 00:00:00 +0800

版本與安全範圍

最後檢視：2026-10-26

內容依 2026-10-26 的 GitLab 官方文件整理，當時最新的 GitLab Runner 為 v19.5.1。設定項目與預設值會隨版本變動，正式環境請先核對 Runner advanced configuration、Runner 註冊與 Predefined CI/CD variables。

privileged = true、掛載 /var/run/docker.sock、gitlab-runner unregister 與 gitlab-runner verify --delete 都有安全或不可復原的風險，下方會個別標示。修改前先備份 config.toml；runner token 與 registry 密碼都是 secret，不要寫進 repository 或 CI log。

註冊 Runner（authentication token 流程）

新的流程是先在 GitLab 建立 runner，再用 runner authentication token 註冊：

Project runner：到 project 的 Settings > CI/CD > Runners，選 Create project runner（需要 Maintainer 角色）。Group 或 instance runner 則在 group 設定或 Admin Area 建立。
設定 tags、描述等屬性後建立，畫面會顯示以 glrt- 開頭的 authentication token，只會短暫顯示一次。
在 runner 主機上註冊：

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --docker-pull-policy "if-not-present" \
  --description "docker-runner"

舊的 registration token（--registration-token）已 deprecated，官方文件標示預計在 GitLab 20.0 移除；新 runner 請一律使用 authentication token。
Tags、protected、run untagged 等屬性改在 GitLab UI 或 API 建立 runner 時設定，不再由 register 參數決定。
自動化建立 runner 可呼叫 POST /api/v4/user/runners，用具備 create_runner scope 的 access token 取得 runner token，再交給 register：

curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners" \
  --data "runner_type=project_type" \
  --data "project_id=<project_id>" \
  --data "description=docker-runner" \
  --data "tag_list=docker,linux" \
  --header "PRIVATE-TOKEN: <project_access_token>"

關於 gitlab_pat：config.toml 沒有 gitlab_pat 這個設定。Runner 連線 GitLab 用的是 [[runners]] 裡的 token（glrt- 開頭的 runner authentication token）；Personal access token（glpat- 開頭）只用在呼叫 API 建立 runner 這類自動化步驟，不需要也不應該寫進 config.toml。

GitLab on Clarence｜Backend、AI、DevOps 與 Infrastructure

GitLab Runner config.toml 設定與常用 CI/CD 變數

版本與安全範圍

註冊 Runner（authentication token 流程）