--- title: "GitLab Runnerとは：executorの選び方と登録手順・config.tomlの設定例【2026年11月】" url: "https://www.issoh.co.jp/tech/details/19633/" published: 2026-11-12 updated: 2026-11-12 categories: ["開発"] publisher: "株式会社一創" --- # 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の公式ドキュメント](https://docs.gitlab.com/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の違い](https://www.issoh.co.jp/tech/details/19631/)で扱っています。 ### Runnerの版はGitLab本体のメジャー.マイナーに合わせて上げる 公式ドキュメントは、Runnerのメジャー.マイナー版をGitLab本体と揃えることを推奨しています。マイナー版の間では後方互換が保証されますが、本体の新機能が同じマイナー版のRunnerを前提にすることがあるためです。 [GitLab Runnerのリリースタグ](https://gitlab.com/gitlab-org/gitlab-runner/-/tags)を見ると、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で本番運用する手順](https://www.issoh.co.jp/tech/details/19667/)で扱っています。 ## RunnerのスコープとGitLab.comのホステッドRunnerを自前構築の前に確認 ### インスタンス・グループ・プロジェクトRunnerの作成権限と使える範囲 Runnerは、どの範囲のプロジェクトにジョブを提供するかで3種類に分かれます。[Runnerの管理ドキュメント](https://docs.gitlab.com/ci/runners/runners%5Fscope/)にある作成権限とジョブの処理順を整理すると次のとおりです。 | スコープ | 使えるプロジェクト | 作成できる人 | ジョブの処理順 | | ------------ | -------------------- | ----------------- | ------- | | インスタンスRunner | インスタンス内の全プロジェクト | 管理者 | 公平利用キュー | | グループRunner | グループとサブグループ内の全プロジェクト | グループのOwner | 先入れ先出し | | プロジェクトRunner | 指定したプロジェクト（複数でも可） | プロジェクトのMaintainer | 先入れ先出し | チームで1台を共有するならグループRunnerが扱いやすい選択です。本番環境へのデプロイ用など、特定のプロジェクトだけに使わせたいRunnerは、プロジェクトRunnerにして「Lock to current projects」で他プロジェクトから有効化できないようにします。 ### GitLab.comのホステッドRunnerはsmallの2 vCPU・8GBが既定 GitLab.comでは、GitLabが運用するインスタンスRunnerがはじめから使えます。[Linux向けホステッドRunnerのドキュメント](https://docs.gitlab.com/ci/runners/hosted%5Frunners/linux/)に載っているx86-64の機種は次のとおりで、タグを書かないジョブはsmallで動きます。 | サイズ | vCPU | メモリ | 使えるプラン | | --------- | ---- | ----- | --------------------- | | small（既定） | 2 | 8GB | Free・Premium・Ultimate | | medium | 4 | 16GB | Free・Premium・Ultimate | | large | 8 | 32GB | Premium・Ultimate | | xlarge | 16 | 64GB | Premium・Ultimate | | 2xlarge | 32 | 128GB | Premium・Ultimate | ジョブで指定するタグは`saas-linux-medium-amd64`のように、サイズ名を`saas-linux-`と`-amd64`で挟んだ形です。 ホステッドRunnerの利用は計算分数で数えられ、Freeは月400分が上限です。[計算分数のドキュメント](https://docs.gitlab.com/ci/pipelines/compute%5Fminutes/)では、計測の対象をインスタンスRunnerの利用分と定義しています。分数が足りなくなったとき、自前のプロジェクトRunnerやグループRunnerへジョブを移すのはこのためです。他のCIサービスの無料枠との比較は[CI/CDツール比較の無料枠と料金](https://www.issoh.co.jp/tech/details/1834/)にまとめています。 ## Docker・Shell・Kubernetes・Autoscalerの選定基準 ### executorの比較はクリーン環境とservices対応と保守状況で見る executorは、Runnerがジョブを「どこで」実行するかを決める設定です。[executorのドキュメント](https://docs.gitlab.com/runner/executors/)の互換性表と保守状況を、選ぶときに効く列だけに絞ると次のようになります。 | executor | ジョブごとのクリーン環境 | services（DB等の併走） | 開発状況 | | ----------------- | ------------ | ---------------- | --------- | | Docker | あり | 使える | 開発継続 | | Docker Autoscaler | あり | 使える | 開発継続 | | Kubernetes | あり | 使える | 開発継続 | | Instance | 条件付き | 使えない | 開発継続 | | Shell・SSH | なし | 使えない | メンテナンスモード | | Docker Machine | あり | 使える | 非推奨 | メンテナンスモードとは、重大なセキュリティ修正だけが入り新機能の予定がない状態です。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の仕組みと採用判断](https://www.issoh.co.jp/tech/details/15574/)で比較できます。 ## GitLab Runnerのインストールと登録手順：Docker executorで動かす ### Ubuntuに公式リポジトリからgitlab-runnerを入れて版を固定する LinuxではGitLabの公式パッケージリポジトリから入れます。[公式リポジトリからのインストール手順](https://docs.gitlab.com/runner/install/linux-repository/)は、リポジトリ追加用のスクリプトを保存して中身を確認してから実行する流れです。 ``` # リポジトリ追加スクリプトを保存し、中身を確認してから実行する 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側へ渡します。[新しい登録方式への移行ドキュメント](https://docs.gitlab.com/ci/runners/new%5Fcreation%5Fworkflow/)のとおり、タグや実行条件はコマンドの引数ではなく、この作成画面で設定します。 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の登録ドキュメント](https://docs.gitlab.com/runner/register/)にある非対話の形で登録します。対話形式の`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`に設定が書き込まれます。[高度な設定のドキュメント](https://docs.gitlab.com/runner/configuration/advanced-configuration/)から、最初に見直す値だけを抜き出した例です。 ``` 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まで）](https://www.issoh.co.jp/tech/details/18874/)でたどれます。ジョブ側の`.gitlab-ci.yml`の書き方全般（rules・needs・変数）は[GitLab CI/CDの.gitlab-ci.ymlの書き方とrules・needs・変数の設定例](https://www.issoh.co.jp/tech/details/19661/)で扱っています。 ## KubernetesでGitLab Runnerを動かすHelmチャートの最小構成 ### helm installでRunnerを入れてジョブごとにPodを作らせる設定 Kubernetesでは、公式のHelmチャートでRunner本体をクラスタに置きます。[GitLab Runner Helmチャートのドキュメント](https://docs.gitlab.com/runner/install/kubernetes/)に沿った最小構成は次のとおりです。 ``` # 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版の違い](https://www.issoh.co.jp/tech/details/7759/)にあります。 ### privilegedの常用と登録トークン方式の延命を見送る判断基準 次のどれかに当てはまる使い方は、その形のまま続けないでください。 - Docker-in-Dockerのために`privileged = true`を、誰でもジョブを流せるインスタンスRunnerやグループRunnerに設定している - `--registration-token`の登録手順を新しいRunnerにも使い回している - 新規のRunnerをShellやDocker Machineで組もうとしている いちばん危ないのは1つ目です。特権コンテナはホストのカーネルにほぼ自由に触れるため、悪意あるコードを含むMRのジョブがRunnerのホストごと乗っ取れます。イメージのビルドが必要ならprivilegedを付けたRunnerを専用のプロジェクトRunnerに分け、ロックしたうえでタグで実行対象を限定する形での運用が必要です。イメージを作った後の検査は[Dockerの脆弱性診断をCI/CDに組み込む手順](https://www.issoh.co.jp/tech/details/3795/)で扱っています。2つ目は20.0で動かなくなる手順を増やすだけなので、今のうちにUIでの作成方式へ移してください。 Runnerの台数やexecutorの設計、Self-Managed本体の更新まで社内で回す人手がない場合は、ホステッドRunnerへ寄せるか、一創の[DevOps・CI/CD導入支援](https://www.issoh.co.jp/service/system/devops/)のように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月】](https://www.issoh.co.jp/tech/details/19631/)：Runnerを含むGitLab全体の構成と提供形態を確認できます - [GitHubとGitLabの違い｜ActionsとGitLab CIの対応表・料金・セルフホスト比較](https://www.issoh.co.jp/tech/details/4219/)：GitHub ActionsとGitLab CIの書き方の違いを対応表で比べられます - [GitLab脆弱性の対応手順：KEV掲載のCVE-2026-97229と修正版19.5.3／19.4.5の判断基準【2026年11月】](https://www.issoh.co.jp/tech/details/18332/)：本体を上げたときにRunnerの版をそろえる判断の参考になります - [CI/CDとは：仕組み・パイプライン構成・GitHub Actionsの設定例と導入判断の基準を解説](https://www.issoh.co.jp/column/details/13002/)：CI/CDの考え方から整理したいときの入口です - [CI/CDツール比較｜主要11製品の無料枠・料金と選び方【2026年10月】](https://www.issoh.co.jp/tech/details/1834/)：GitLab CI以外のサービスと無料枠を比較できます --- 出典: [GitLab Runnerとは：executorの選び方と登録手順・config.tomlの設定例【2026年11月】]()（株式会社一創）