GitLabで自動の処理を試すと、「Runner」という言葉に必ず出会います。設定ファイルは書いたのに、仕事が「pending」のまま動かない、という場面で初めて調べる人も多いです。Runnerが何をしているのか、用意されたものと自分で立てるものはどう違うのかを、サンプル料理教室の menu.html のチェックを例に順に書きます。読み終わると、自社で立てる必要があるかどうかを判断できます。
この記事の内容
先に答えると
GitLab Runnerは、.gitlab-ci.yml に書いた仕事を実際に動かすプログラムです。GitLab.comなら、GitLabが用意したRunnerがそのまま使えます。小さな会社のチェックや公開の処理なら、まず自分で立てなくて構いません。
.gitlab-ci.ymlは指示書、Runnerはそれを実行する側- GitLab.comのFreeは月400コンピュート分。用意されたRunnerを使うと減る（2026年11月時点）
- 自分で立てるのが要るのは、社内サーバーへ配るとき、分数が足りないときなど
- 登録は
glrt-で始まる runner authentication token を使う。古い登録トークンは廃止予定 - 自分のRunnerはプロジェクトのコードをそのサーバーで動かす。信頼できる人のコードだけに使う
CI/CDとRunnerの関係
CI/CDは、pushなどをきっかけにチェックや公開を自動で動かす仕組みです。GitLabでは、3つの部品が順に動きます。
| 部品 | 何か | 料理教室の例 |
|---|---|---|
.gitlab-ci.yml | 何をするかを書いた設定ファイル | menu.html に「円」があるか調べる |
| GitLab | 設定を読み、仕事を順番待ちに並べる | pushされたので仕事を1件並べる |
| Runner | 順番待ちの仕事を取りに行って動かす | コマンドを実行し、結果を返す |
GitLabの画面にあるのは指示と結果で、コマンドを動かしているのはRunnerです。どんなに正しく設定を書いても、動かす側がいなければ仕事は始まりません。
GitHub Actionsを知っているなら、同じ考え方です。
| GitHub Actions | GitLab | 役割 |
|---|---|---|
| ワークフローのファイル | .gitlab-ci.yml | 設定ファイル |
| runner | Runner | 実際に動かす側 |
on: | rules: | いつ動くか |
run: | script: | 何を実行するか |
runs-on: | tags: | どこで動かすか |
.gitlab-ci.yml の読み方
menu.html に「円」があるかを調べる最小の例です。次の書式はGitLabの公式の説明で確かめたもので、GitLab上でのパイプラインの実行はしていません。
stages:
- check
check-menu:
stage: check
script:
- grep -q "円" menu.htmlcheck-menu が仕事（job）の名前です。読み方は次のとおりです。
| 書き方 | 意味 | この例 |
|---|---|---|
stages | 段階の順番 | check の1段階 |
| job | 仕事の単位。名前は自分で決める | check-menu |
stage | その仕事がどの段階か | check |
script | 実行するコマンド | grep で調べる |
rules | 動かす条件 | 下の例 |
artifacts | 仕事のあとに残すファイル | 下の例 |
tags | どのRunnerで動かすか | 下の例 |
grep -q "円" menu.html だけは手元で動かしました。
$ grep -q "円" menu.html; echo $?
0見つかると0を返します。「円」を消して同じことをすると1です。Runnerはこの終了コード（処理の結果を表す数字）で成功か失敗かを決めます。0以外なら仕事は失敗です。
main のときだけ動かす、結果をファイルで残す、自分のRunnerを指定する、を足すと次のようになります。同じく書式の確認までで、実行はしていません。
check-menu:
stage: check
script:
- grep "円" menu.html > check-result.txt
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
artifacts:
paths:
- check-result.txt
expire_in: 1 week
tags:
- sample-cooking-serverartifacts の paths はプロジェクトのフォルダからの相対の場所で書きます。expire_in は保存しておく期間です。tags はGitの「タグ」とは別物で、Runnerにつける札です。公式の説明も、CI/CDのタグはRunnerに、Gitのタグはコミットにつくものと分けています。
用意されたRunnerと、自分で立てるRunner
| 比べるところ | GitLabが用意するRunner | 自分で立てるRunner |
|---|---|---|
| 公式の呼び方 | GitLab-hosted runners。インスタンスRunnerの一種 | self-managed runners |
| 置き場所 | GitLabが管理 | 自社のサーバーやパソコン |
| 準備 | なし | インストールして登録する |
| 枠 | コンピュート分が減る | コンピュート分の計測の対象はインスタンスRunnerの利用 |
| 費用 | プランの枠の中。超えたら追加 | サーバー代と保守の手間 |
| 動く環境 | 毎回きれいな環境 | executorの選び方で変わる |
GitLab.comのFreeは月400コンピュート分です（2026年11月時点）。コンピュート分は、動いた時間に機械の大きさの係数を掛けたものです。既定のRunnerのタグは saas-linux-small-amd64 で、vCPU 2、メモリ8GBです。1回1分で終わるチェックなら、係数を1倍として計算すると月400回まで動かせます。料理教室の修正の頻度なら、まず足りません。
自分で立てるRunnerには、使える範囲の違いが3つあります。
| 種類 | 使える範囲 | 作れる人 |
|---|---|---|
| インスタンスRunner | そのGitLab全体 | Self-Managedの管理者（GitLab.comでは作れない） |
| グループRunner | グループ内の複数プロジェクト | グループのOwner |
| プロジェクトRunner | 指定したプロジェクト | プロジェクトのMaintainer |
Self-Managed（自社サーバーで動かすGitLab）のFreeは、Runnerも自分で用意します。GitLabとは別のサーバーに入れるよう公式は案内しています。Runnerの話が必ず付いてくるのはこのためです。
自分で立てるのが要る場面、要らない場面
| 場面 | 要るか | 理由 |
|---|---|---|
menu.html のチェックだけ | 要らない | 用意されたRunnerで足りる |
| 公開先が外から入れる場所 | たいてい要らない | 鍵を変数に入れれば用意されたRunnerから送れる |
| 社内のネットワークの中のサーバーへ配る | 要る | 外から入れない場所には内側のRunnerが要る |
| 毎月の分数が足りない | 検討する | プランや追加購入の費用と、サーバーの費用を比べる |
| 特別な機材やソフトが要る | 要る | 用意された環境にないものは自分で持つ |
| Self-Managedで運用している | 要る | Runnerは自分で用意する |
実際に運用していると、分数が足りない原因は機械の不足より、毎回全部を動かす設定にあることが多いです。自分で立てる前に、rules で動かす条件を絞ると減ります。自分で立てると、OSの更新、ディスクの掃除、止まったときの対応も自社の仕事になります。
自分で立てる手順
ここからはGitLab.comのプロジェクト sample-cooking/website に、Linuxのサーバー1台をつなぐ流れです。公式の手順を確かめて書いたもので、このコマンドは実行していません。本物のサーバーとGitLabが要るからです。
Runnerを入れる
Debian系のLinuxの場合です。macOS、Windows、Dockerで動かす方法もあります。
- リポジトリの設定を入れるスクリプトを取ってくる
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- Runnerを入れる
sudo apt install gitlab-runnerGitLabの画面でRunnerを作る
プロジェクトのMaintainerの権限が要ります。
- プロジェクトを開く
- 左の「Settings」の「CI/CD」を開く
- 「Runners」の欄を開く
- 「Create project runner」を押す
- OSを選ぶ
- 「Tags」に
sample-cooking-serverと入れる - 「Create runner」を押す
タグをつけない仕事も動かしたいなら、「Run untagged」を選びます。
画面に runner authentication token が出ます。glrt- で始まる文字列で、表示されるのは登録のあいだの短い時間だけです。鍵と同じ扱いにします。
登録する
サーバーで次を実行します。
sudo gitlab-runner register順に聞かれます。
| 聞かれること | 入れる値 |
|---|---|
| GitLab instance URL | https://gitlab.com |
| トークン | glrt-xxxxxxxx |
| 説明 | sample-cooking-server |
| ジョブのタグ（カンマ区切り） | sample-cooking-server |
| メモ | 空でいい |
| executor | docker |
聞かれる項目はバージョンで変わることがあります。登録の結果は config.toml に保存されます。このファイルにもトークンが入るので、人に渡しません。
質問に答えず1行で登録することもできます。
sudo gitlab-runner register --non-interactive --url "https://gitlab.com" --token "glrt-xxxxxxxx" --executor "docker" --docker-image alpine:latest --description "docker-runner"つながったかどうかは次で見ます。
sudo gitlab-runner verify古い登録トークンのこと
古い記事には、プロジェクトの設定画面で登録トークンをコピーする手順が載っていることがあります。これは registration token で、公式は非推奨としており、GitLab 20.0で取り除く予定と書いています（2026年11月時点）。--registration-token と書かれていたら古いやり方です。新しく立てるなら --token と runner authentication token を使います。
executorの違い
executorは、Runnerが仕事をどこで動かすかの方式です。公式には他にもKubernetesなどがあります。小さな会社が最初に比べるのはこの2つです。
| 比べるところ | shell | docker |
|---|---|---|
| どこで動くか | Runnerのサーバーでそのまま | コンテナ（隔離された環境）の中 |
| 毎回きれいな環境か | いいえ | はい |
| 前提 | Runnerが入っていれば動く | サーバーにDockerが要る |
| 依存するソフト | サーバーに入れておく | イメージにまとめる |
| 問題を調べるとき | 楽 | 普通 |
| 開発の状況 | 保守のみで新機能なし | 続いている |
| 向く場面 | 信頼できる仕事だけ。社内の決まった作業 | まず選ぶならこちら |
迷ったら docker です。shellは前の仕事の残りがサーバーに残ることがあり、「昨日は動いたのに今日は動かない」の原因になります。
セキュリティで気をつけること
自分のRunnerは、プロジェクトに書かれたコードをそのサーバーで実行します。公式の安全のページにある要点は次のとおりです。
- プロジェクトのDeveloperの権限がある人なら、故意でなくてもRunnerのサーバーの安全を損なえる
- 複数のプロジェクトで同じRunnerを使い続けると、危険は大きくなる
- 乗っ取られた環境では、仕事に渡された秘密の変数を盗まれる
- shell executorは、サーバーとネットワークに高いリスクがある。仕事はRunnerのユーザーの権限で動き、同じサーバーで動く他のプロジェクトのコードを盗める。信頼できる仕事だけに使う
ここから言えることを、料理教室に当てはめます。
- 公開プロジェクトや、知らない人のコードが入るプロジェクトには、自分のRunnerをつながないほうが安全です。公式に明記はなく、運用上の経験則です。Developerの権限があればジョブを動かせるので、知らない人にその権限が渡りうるためです
- 非公開プロジェクトでも、外注エンジニアBのようにDeveloper以上を渡した人のコードは動く。渡す相手を選ぶ
- 社内の他のサーバーに届く場所に置かない。公式は、悪意のある仕事の影響を減らすために、別のネットワーク区画で動かすことを検討できると書いている
reservation-mailの鍵を使う仕事は、保護された枝（protected branch）だけで動かす。Runnerの設定の「Protected」で絞れる
GitLabが用意するRunnerなら、この管理はGitLab側の仕事です。自分で立てる判断は、この手間ごと引き受ける判断です。
失敗したときに見る場所
| 見る場所 | 何が分かるか |
|---|---|
| 左の「Build」の「Pipelines」 | pushごとの全体の結果 |
| 左の「Build」の「Jobs」 | 仕事ごとの状態 |
| 仕事の詳細のログ | どのコマンドで失敗したか |
| 「Settings」の「CI/CD」の「Runners」 | Runnerがつながっているか |
ログの最後のほうを読むと、たいてい原因が書いてあります。grep の例なら、exit code 1 のような表示で失敗の行が分かります。
仕事が動き出さず待ちのままなら、ログより先にタグを疑います。公式の例では、タグつきの仕事だけを受けるRunnerに、タグのない仕事を出すと止まったままになります（stuck）。逆に、Runnerにない tags を書いた仕事も、受け取るRunnerがいません。
GitLabは待ち続ける仕事を自動で落とします。公式の説明では、合うRunnerがいないまま1時間待つと stuck_pending_no_matching_runners、合うRunnerがいるのに24時間動かないと stuck_pending_with_matching_runners という理由で落ちます（2026年11月時点）。
できないことと、その代わり
| できないこと | その代わり |
|---|---|
Runnerなしで .gitlab-ci.yml を動かす | 用意されたRunnerを使うか、自分で立てる |
| 外のRunnerから社内だけのサーバーに直接届く | 社内に自分のRunnerを置く |
| shell executorで仕事どうしを隔離する | docker executorにする |
| トークンを後で画面からもう一度見る | Runnerを作り直す。保存は config.toml にある |
| 無料枠を超えても動かし続ける | プランを上げる、分数を買う、自分で立てる |
よく詰まるところ
| 症状 | 原因 | 直し方 |
|---|---|---|
| 仕事が pending のまま | タグが合わない、Runnerが止まっている | 「Runners」で状態とタグを見る。tags を直す |
| タグのない仕事が動かない | Runnerがタグつきだけを受ける設定 | 「Run untagged」を選ぶ |
Check registration token のエラー | トークンが受け付けられていない | トークンの値や種類を確かめる。作り直したときは、新しいトークンで登録する |
410 Gone - runner registration disallowed | 登録トークンでの登録が無効になっている | runner authentication token に切り替える |
| shellで動いたり動かなかったりする | 前の仕事の残りがある、サーバーのソフトが違う | dockerに変える。サーバーの中身を確かめる |
| 自分のRunnerがあるのに分数が減る | 用意されたRunnerで動いている | tags を書く。「Turn on runners for this project」を切る |
grep の行で失敗する | ファイルに語がない、終了コードが0以外 | ログで確かめ、ファイルを直す |
インスタンスRunnerの切り替えは、プロジェクトの「Settings」の「CI/CD」の「Runners」にあります。Ownerの権限が要ります。
次に読む
GitLab全体の使い方と無料の範囲は「GitLabの使い方：無料の範囲、CI/CD、GitHubからの移行」に、GitHub側の同じ仕組みは「GitHub Actionsの使い方：自動で動かす仕組みと無料枠」に書きました。どちらのサービスを使うか迷っているなら「GitHubとGitLabの違い：料金・機能・自社サーバーで比べる選び方」、GitHubの枠と費用は「GitHubの料金：Free・Team・Enterpriseと無料でできる範囲」です。