GitLab Runner config.toml 設定とよく使う CI/CD 変数

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

Version と安全範囲

最終確認：2026年10月26日

2026年10月26日時点の GitLab 公式ドキュメントをもとに整理しています。当時の最新 GitLab Runner は v19.5.1 です。設定項目や default 値は version によって変わるため、本番環境では Runner advanced configuration、Runner の登録、Predefined CI/CD variables を確認してください。

privileged = true、/var/run/docker.sock の mount、gitlab-runner unregister、gitlab-runner verify --delete には security 上または取り消せないリスクがあり、以下で個別に示します。変更前に config.toml を backup してください。Runner token や registry password は secret です。repository や CI log に残さないでください。

Runner の登録（authentication token 方式）

現在の手順では、先に GitLab で runner を作成し、runner authentication token で登録します。

Project runner の場合、project の Settings > CI/CD > Runners で Create project runner を選択します（Maintainer role が必要）。Group runner や instance runner は group 設定または Admin Area で作成します。
Tags や説明を設定して作成すると、glrt- で始まる authentication token が短時間だけ表示されます。
Runner host で登録します。

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 作成を自動化する場合は、create_runner scope を持つ access token で POST /api/v4/user/runners を呼び出し、返された 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- で始まる）は runner 作成などの API 自動化にだけ使い、config.toml に書く必要はありません。

GitLab on Clarence｜Backend・AI・DevOps・Infrastructure

GitLab Runner config.toml 設定とよく使う CI/CD 変数

Version と安全範囲

Runner の登録（authentication token 方式）