GitLab Runnerとは：executorの選び方と登録手順・config.tomlの設定例【2026年11月】

GitLab Runnerとは、GitLab CI/CDのパイプラインに書いたジョブを受け取り、実際に実行するアプリケーションです。GitLab本体とは別にインストールし、どこで・どの方式（executor）でジョブを動かすかを決めてから登録します。本記事では、Runnerのスコープの違い、Docker・Shell・Kubernetesなどexecutorの選び方、glrt-で始まる認証トークンを使った登録コマンド、config.tomlとHelmの設定例を、公式ドキュメントの該当箇所へのリンクつきで解説します。版や仕様は2026年11月12日時点の公式情報です。

まとめ：GitLab Runnerはジョブの実行役、登録はglrt-トークンで行う

GitLab本体はジョブの「割り当て」までしか行いません。ビルドやテストを実行するのはRunnerで、RunnerがGitLabへジョブを取りに行く方式なので、Runner側に受信ポートを開ける必要はありません。

GitLab.comを使っているなら、まずはGitLabが用意するホステッドRunnerで足ります。自前のRunnerが必要になるのは、社内ネットワークの資源へ届かせたいとき、大きいマシンやGPUが要るとき、Self-Managedで運用しているときです。

自前で立てるときのexecutorは、迷ったらDockerを選びます。登録はUIでRunnerを作成してglrt-で始まる認証トークンを受け取り、gitlab-runner registerに渡す新方式で行います。旧来の登録トークンはGitLab 20.0で削除予定です。

GitLab Runnerとは何か：GitLab本体とジョブをやり取りする仕組みと版

GitLab Runnerの定義とジョブを取りに行くポーリングの流れ

GitLab Runnerの公式ドキュメントは、Runnerを「GitLab CI/CDと連携してパイプラインのジョブを実行するアプリケーション」と定義しています。開発者が.gitlab-ci.ymlに書いたテストやビルドの手順を、実際のマシンやコンテナの上で動かす役です。

動きは単純です。RunnerはGitLabに対して一定間隔で「実行できるジョブはあるか」を問い合わせ、割り当てられたジョブを実行し、ログと結果をGitLabへ送り返します。問い合わせの間隔はcheck_intervalで、既定は3秒です。通信はRunnerからGitLabへの外向きHTTPSだけなので、社内ネットワークの中に置いたRunnerでも、GitLab.comのジョブを処理できます。

GitLab本体の中でRunnerがどの位置にあるか、なぜ別インストールなのかはGitLabの構成要素とCE・EEの違いで扱っています。

Runnerの版はGitLab本体のメジャー.マイナーに合わせて上げる

公式ドキュメントは、Runnerのメジャー.マイナー版をGitLab本体と揃えることを推奨しています。マイナー版の間では後方互換が保証されますが、本体の新機能が同じマイナー版のRunnerを前提にすることがあるためです。

GitLab Runnerのリリースタグを見ると、2026年11月5日にv19.5.3・v19.4.4・v19.3.6が同時に出ています。本体と同じく直近3つのマイナー版へ修正が入る形です。Self-Managedで本体を19.5に上げたら、Runnerも19.5系へ上げる、という順番で運用表に組み込むと漏れません。Self-Managed本体をDocker Composeで構築・更新する手順はGitLabオンプレ構築：Docker Composeで本番運用する手順で扱っています。

RunnerのスコープとGitLab.comのホステッドRunnerを自前構築の前に確認

インスタンス・グループ・プロジェクトRunnerの作成権限と使える範囲

Runnerは、どの範囲のプロジェクトにジョブを提供するかで3種類に分かれます。Runnerの管理ドキュメントにある作成権限とジョブの処理順を整理すると次のとおりです。

チームで1台を共有するならグループRunnerが扱いやすい選択です。本番環境へのデプロイ用など、特定のプロジェクトだけに使わせたいRunnerは、プロジェクトRunnerにして「Lock to current projects」で他プロジェクトから有効化できないようにします。

GitLab.comのホステッドRunnerはsmallの2 vCPU・8GBが既定

GitLab.comでは、GitLabが運用するインスタンスRunnerがはじめから使えます。Linux向けホステッドRunnerのドキュメントに載っているx86-64の機種は次のとおりで、タグを書かないジョブはsmallで動きます。

ジョブで指定するタグはsaas-linux-medium-amd64のように、サイズ名をsaas-linux-と-amd64で挟んだ形です。

ホステッドRunnerの利用は計算分数で数えられ、Freeは月400分が上限です。計算分数のドキュメントでは、計測の対象をインスタンスRunnerの利用分と定義しています。分数が足りなくなったとき、自前のプロジェクトRunnerやグループRunnerへジョブを移すのはこのためです。他のCIサービスの無料枠との比較はCI/CDツール比較の無料枠と料金にまとめています。

Docker・Shell・Kubernetes・Autoscalerの選定基準

executorの比較はクリーン環境とservices対応と保守状況で見る

executorは、Runnerがジョブを「どこで」実行するかを決める設定です。executorのドキュメントの互換性表と保守状況を、選ぶときに効く列だけに絞ると次のようになります。

メンテナンスモードとは、重大なセキュリティ修正だけが入り新機能の予定がない状態です。Shellはこの扱いで、Docker Machineは非推奨です。これから新しく組むRunnerを、この2つの上に載せる理由はほとんどありません。

迷ったらDocker、Shellを選ぶのはホストの道具を使うときだけ

実務では、最初にDocker executorを選んでおけば外れません。ジョブごとに新しいコンテナで始まるので、前のジョブが残したファイルや入れたパッケージに次のジョブが引きずられません。services:でPostgreSQLなどをテスト中だけ立てられるのもDocker系の利点です。

Shellは、Runnerを入れたマシンのOSでそのままコマンドを実行します。設定は最小ですが、ビルドごとに環境が初期化されず、同時実行させるとジョブ同士が同じディレクトリやサービスを取り合う構成です。Shellを選ぶのは、Windows専用のビルドツールや実機につないだテスト機材など、ホストにしかない道具を使うときに限ります。

ジョブ数の山と谷が大きいなら、Kubernetes（ジョブごとにPodを作る）か、クラウドのVMを必要なときだけ増やすDocker Autoscalerを選びます。Kubernetes上のCIを専用の仕組みで組む選択肢はKubernetesネイティブに動くTektonの仕組みと採用判断で比較できます。

GitLab Runnerのインストールと登録手順：Docker executorで動かす

Ubuntuに公式リポジトリからgitlab-runnerを入れて版を固定する

LinuxではGitLabの公式パッケージリポジトリから入れます。公式リポジトリからのインストール手順は、リポジトリ追加用のスクリプトを保存して中身を確認してから実行する流れです。

# リポジトリ追加スクリプトを保存し、中身を確認してから実行する
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" -o script.deb.sh
less script.deb.sh
sudo bash script.deb.sh

# 最新版を入れる場合
sudo apt install gitlab-runner

# 本体の版に合わせて固定する場合（helper-images も同じ版を指定する）
apt-cache madison gitlab-runner
sudo apt install gitlab-runner=19.5.3-1 gitlab-runner-helper-images=19.5.3-1

版を指定するときは、v17.7.1以降gitlab-runner-helper-imagesも同じ版を明示しないと依存関係のエラーで止まります。Docker executorを使うなら、同じホストにDocker Engineも入れておきます。

UIでプロジェクトRunnerを作成しglrt-で始まるトークンを受け取る

いまの登録方式では、先にGitLabの画面でRunnerを作成し、そこで発行される認証トークンをRunner側へ渡します。新しい登録方式への移行ドキュメントのとおり、タグや実行条件はコマンドの引数ではなく、この作成画面で設定します。

1. プロジェクトを開き、左サイドバーの「Settings」から「CI/CD」を選ぶ
2. 「Runners」セクションを展開し、「Create project runner」を選ぶ
3. Runnerを入れたOS（Linuxなど）を選び、Tagsにdocker-linuxのようなタグを入れる
4. タグなしのジョブも受けるなら「Run untagged」にチェックを入れ、「Create runner」を選ぶ
5. 表示されたglrt-で始まるトークンを控える

トークンはこの画面でしか全体を確認できないので、すぐにRunnerのホストで登録まで進めます。グループRunnerなら同じ手順をグループの「Build」→「Runners」から行います。

gitlab-runner registerでDockerを非対話登録する手順

受け取ったトークンを環境変数に入れ、Runnerの登録ドキュメントにある非対話の形で登録します。対話形式のsudo gitlab-runner registerでも同じ項目を聞かれますが、手順書やスクリプトに残すなら非対話のほうが再現できます。

# UI で受け取った認証トークン（glrt- で始まる）を入れる
export RUNNER_TOKEN="glrt-xxxxxxxxxxxxxxxxxxxx"

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

# 登録内容と GitLab への接続を確かめる
sudo gitlab-runner list
sudo gitlab-runner verify

Self-Managedなら--urlを自社GitLabのURLに変えます。旧来の--registration-token方式は非推奨で、GitLab 20.0で削除予定です。この旧方式の引数に新しいトークンを渡すと互換モードで動きますが、--tag-listや--lockedは無視されるので、タグはUI側で付け直す必要があります。

config.toml：concurrent・limit・privileged設定例

登録が終わると、rootで動かしている場合は/etc/gitlab-runner/config.tomlに設定が書き込まれます。高度な設定のドキュメントから、最初に見直す値だけを抜き出した例です。

concurrent = 4          # このホスト全体で同時に動かすジョブ数の上限（0 は不可）
check_interval = 3      # ジョブを問い合わせる間隔（秒）。既定は 3

[[runners]]
  name = "docker-runner"
  url = "https://gitlab.com/"
  token = "glrt-xxxxxxxxxxxxxxxxxxxx"
  executor = "docker"
  limit = 2             # この Runner が同時に受けるジョブ数。0（既定）は無制限
  request_concurrency = 1
  [runners.docker]
    image = "alpine:latest"
    privileged = false  # true は Docker-in-Docker 用。公式は Insecure と注記
    pull_policy = ["if-not-present"]
    volumes = ["/cache"]

同時実行数はconcurrentが全体の上限、limitがRunnerごとの上限です。ホストのCPUコア数を超えて並べるとジョブ同士が遅くなるだけなので、4コアなら4程度から始めます。pull_policyの既定はalwaysで毎回イメージを取りに行くため、Docker Hubの取得回数制限に当たるならif-not-presentへの変更が対応策です。編集後はsudo gitlab-runner restartで反映します。

.gitlab-ci.ymlのtagsで自前Runnerにジョブを割り当てて確認

Runnerにタグを付けた場合、ジョブ側に同じタグを書くとそのRunnerで実行されます。

stages:
  - test

runner-check:
  stage: test
  tags:
    - docker-linux        # UI で Runner に付けたタグと揃える
  image: alpine:latest
  script:
    - echo "runner: $CI_RUNNER_DESCRIPTION"
    - uname -a

パイプラインを実行し、ジョブログの先頭に「Running with gitlab-runner 19.5.x」と登録時のdescriptionが出れば、自前Runnerで動いています。プロジェクトの作成からパイプライン実行までの画面操作はGitLabの使い方（プロジェクト作成からIssue・MR・CI/CDまで）でたどれます。ジョブ側の.gitlab-ci.ymlの書き方全般（rules・needs・変数）はGitLab CI/CDの.gitlab-ci.ymlの書き方とrules・needs・変数の設定例で扱っています。

KubernetesでGitLab Runnerを動かすHelmチャートの最小構成

helm installでRunnerを入れてジョブごとにPodを作らせる設定

Kubernetesでは、公式のHelmチャートでRunner本体をクラスタに置きます。GitLab Runner Helmチャートのドキュメントに沿った最小構成は次のとおりです。

# values.yaml
gitlabUrl: https://gitlab.example.com/
runnerToken: "glrt-xxxxxxxxxxxxxxxxxxxx"
rbac:
  create: true            # ジョブ用の Pod を作る権限を Runner に与える

# リポジトリを追加してインストールする
helm repo add gitlab https://charts.gitlab.io
helm repo update
kubectl create namespace gitlab-runner
helm install --namespace gitlab-runner gitlab-runner -f values.yaml gitlab/gitlab-runner

この構成ではRunner本体が1つのPodとして常駐し、ジョブが来るたびに別のPodを作って実行します。トークンをvalues.yamlに直接書くとGitの履歴に残るので、本番ではKubernetesのSecretに入れて参照させます。

自前Runnerの構築判断：採用条件と運用を見送るべき具体的な場面

自前Runnerを立てるのは社内資源への到達か大きいマシンが要る場合

GitLab.comを使っていて、自前のRunnerを立てる理由がはっきりするのは次の3つです。1つ目は、ジョブから社内のDBや検証サーバーへ届かせたいとき。外向き通信だけで動くRunnerを社内に置けば、受信ポートを開けずに済みます。2つ目は、ホステッドRunnerにない構成が要るとき（GPU、Windowsの特定ツール、大量メモリ）。3つ目は、計算分数の上限に毎月当たるときです。

Self-Managedでは、Runnerは本体に同梱されないので自前構築が前提です。GitHub Actionsでも同じ考え方で、そちらの手順はGitHubセルフホストランナーの導入手順とhosted版の違いにあります。

privilegedの常用と登録トークン方式の延命を見送る判断基準

次のどれかに当てはまる使い方は、その形のまま続けないでください。

• Docker-in-Dockerのためにprivileged = trueを、誰でもジョブを流せるインスタンスRunnerやグループRunnerに設定している
• --registration-tokenの登録手順を新しいRunnerにも使い回している
• 新規のRunnerをShellやDocker Machineで組もうとしている

いちばん危ないのは1つ目です。特権コンテナはホストのカーネルにほぼ自由に触れるため、悪意あるコードを含むMRのジョブがRunnerのホストごと乗っ取れます。イメージのビルドが必要ならprivilegedを付けたRunnerを専用のプロジェクトRunnerに分け、ロックしたうえでタグで実行対象を限定する形での運用が必要です。イメージを作った後の検査はDockerの脆弱性診断をCI/CDに組み込む手順で扱っています。2つ目は20.0で動かなくなる手順を増やすだけなので、今のうちにUIでの作成方式へ移してください。

Runnerの台数やexecutorの設計、Self-Managed本体の更新まで社内で回す人手がない場合は、ホステッドRunnerへ寄せるか、一創のDevOps・CI/CD導入支援のようにCI/CD基盤の構築と保守を外部に任せる形を検討してください。

よくある質問

GitLab Runnerについて調べている方から多い質問に、2026年11月時点の公式情報をもとに回答します。

GitLab Runnerは無料で使えますか？

Runnerのソフトウェア自体は無料で、自分のサーバーやPCに入れて使えます。費用がかかるのは、Runnerを動かすマシンの代金です。GitLab.comのホステッドRunnerを使う場合は計算分数を消費し、Freeプランは月400分までです。分数が足りなくなったら、自前のRunnerを登録してジョブをそちらへ回すと上限を気にせず動かせます。

GitLab RunnerとGitHub Actionsのランナーは何が違いますか？

役割は同じで、CIのジョブを受け取って実行するプログラムです。違うのは連携先と設定方法で、GitLab RunnerはGitLabのUIで作成したRunnerに認証トークンで登録し、executorでDockerやKubernetesなどの実行方式を選びます。GitHubのセルフホストランナーにはexecutorの概念がなく、ホスト上で直接ジョブを実行するのが基本です。

GitLab Runnerはどこにインストールすればよいですか？

GitLab本体とは別のマシンに入れるのが基本です。ビルドやテストはCPUとメモリを大きく使うため、同じサーバーに置くと本体の画面やAPIの応答が遅くなります。社内のDBなどへ届かせたい場合は社内ネットワーク、ジョブ数の増減が大きい場合はKubernetesクラスタやクラウドのVMに置きます。

Runnerが「stuck」のままジョブを実行しないのはなぜですか？

多いのはタグの不一致です。ジョブのtagsと一致するタグを持つRunnerがない、またはRunnerが「Run untagged」をオフにしているのにジョブにタグがない場合、ジョブは割り当て待ちのまま止まります。そのほか、Runnerが一時停止（paused）になっている、保護ブランチ用に限定したRunnerに通常ブランチのジョブが来ている、なども確認します。

executorは後から変更できますか？

executorは登録後に変更可能です。config.tomlのexecutorと対応する設定セクションを書き換えて再起動するか、同じトークンで登録し直します。ただしShellからDockerへ変えると、ホストに入っていたツールがジョブから見えなくなります。必要なツールを入れたイメージを先に用意し、image:で指定してから切り替えてください。

関連記事

• GitLabとは：構成要素・CEとEEの違い・3つの提供形態とDockerで試す手順【2026年11月】：Runnerを含むGitLab全体の構成と提供形態を確認できます
• GitHubとGitLabの違い｜ActionsとGitLab CIの対応表・料金・セルフホスト比較：GitHub ActionsとGitLab CIの書き方の違いを対応表で比べられます
• GitLab脆弱性の対応手順：KEV掲載のCVE-2026-97229と修正版19.5.3／19.4.5の判断基準【2026年11月】：本体を上げたときにRunnerの版をそろえる判断の参考になります
• CI/CDとは：仕組み・パイプライン構成・GitHub Actionsの設定例と導入判断の基準を解説：CI/CDの考え方から整理したいときの入口です
• CI/CDツール比較｜主要11製品の無料枠・料金と選び方【2026年10月】：GitLab CI以外のサービスと無料枠を比較できます