glab-runner

glab runner

コマンドラインから GitLab CI/CD ランナーを管理します。

クイックスタート

# List runners for current project
glab runner list

# Pause a runner
glab runner update <runner-id> --pause

# Delete a runner
glab runner delete <runner-id>

よくあるワークフロー

ランナーを一覧表示する

# List all runners for current project
glab runner list

# List for a specific project
glab runner list --repo owner/project

# List all runners (instance-level, admin only)
glab runner list --instance

# Output as JSON
glab runner list --output json

# Paginate
glab runner list --page 2 --per-page 50

JSON 出力の解析例：

# Find all paused runners
glab runner list --output json | python3 -c "
import sys, json
runners = json.load(sys.stdin)
paused = [r for r in runners if r.get('paused')]
for r in paused:
    print(f"{r['id']}: {r.get('description','(no description)')} — {r.get('status')}")
"

ランナーを一時停止または再開する

ランナーを一時停止すると、削除せずに新しいジョブの取得を防止できます。

# Pause runner 123
glab runner update 123 --pause

# Resume a paused runner
glab runner update 123 --unpause

# Pause in a specific project context
glab runner update 123 --pause -R owner/project

一時停止する場面：

• メンテナンス期間中（更新、再起動）
• ランナーの障害を調査する場合
• 一時的にランナーの処理能力を減らす場合
• 廃止する前（最初にジョブが実行中でないことを確認してください）

注： 古いドキュメントや例では glab runner pause に言及している場合がありますが、サポートされているコマンドは glab runner update --pause / --unpause です。

ランナーが処理したジョブを確認する

# List recent jobs for runner 9
glab runner jobs 9

# Show only running jobs
glab runner jobs 9 --status running

# JSON output for automation
glab runner jobs 9 --output json

一時停止または削除する前に、ランナーが現在ビジーかどうかを確認するのに便利です。

ランナーマネージャーを確認する

# List managers attached to a runner
glab runner managers 9

# JSON output
glab runner managers 9 --output json

ランナーに関連付けられているランナーマネージャーのプロセスやバックエンドを把握する必要がある場合に使用します。

ランナーを削除する

# Delete with confirmation prompt
glab runner delete 123

# Delete without confirmation
glab runner delete 123 --force

# Delete in a specific project context
glab runner delete 123 --repo owner/project

⚠️ 削除は取り消せません。 判断に迷う場合は、先に一時停止してください。

判断フロー：一時停止と削除の使い分け

Do you need the runner gone permanently?
├─ No → Pause it (recoverable)
└─ Yes → Is it actively running jobs?
          ├─ Yes → Check `glab runner jobs <id>`, then pause first and wait for jobs to finish
          └─ No → Delete with --force

ランナーのステータス一覧

ステータス	意味
online	接続済みで、ジョブを受け付ける準備ができています
offline	未接続です（ランナープロセスを確認してください）
paused	接続済みですが、新しいジョブを受け付けていません
stale	過去 3 か月間、連絡がありません

トラブルシューティング

「runner: command not found」：

• 現行の glab リリースが必要です。glab version で確認してください。

インスタンスレベルのランナーで「Permission denied」が発生する：

• インスタンスレベルのランナー管理には、GitLab 管理者権限が必要です。
• プロジェクトのランナーは、プロジェクトのメンテナーが管理できます。

ランナーを一時停止または再開できない：

• glab runner list でランナー ID を確認してください。
• 権限を確認してください（プロジェクトで少なくとも Maintainer 権限が必要です）。
• glab runner update <id> --pause または --unpause を使用してください。

一時停止後もランナーが「online」のままになる：

• ホスト上ではランナープロセスが引き続き実行されています。ただし、新しいジョブは受け付けません。
• これは想定どおりの動作です。完全に停止するには、ランナーのホストに SSH で接続し、プロセスを停止してください。

ランナーを削除できない：

• ランナーが共有またはグループレベルである可能性があります（より高い権限が必要です）。
• ランナーが複数のプロジェクトに割り当てられているか確認してください。1 つのプロジェクトから削除する場合、インスタンスレベルではなくプロジェクトレベルで削除する必要があることがあります。

プロジェクトへのランナーの割り当て／割り当て解除

既存のランナーをプロジェクトに割り当てると、ジョブを取得できるようになります。

# Assign a runner to the current project
glab runner assign <runner-id>

# Assign to a specific project
glab runner assign <runner-id> --repo owner/project

プロジェクトからランナーを削除します（ランナー自体は削除されません）。

# Unassign from current project
glab runner unassign <runner-id>

# Unassign from a specific project
glab runner unassign <runner-id> --repo owner/project

注： 割り当てと割り当て解除には、プロジェクトで少なくとも Maintainer ロールが必要です。これは、ランナーを完全に削除する glab runner delete とは異なります。

関連スキル

• glab-runner-controller — ランナーコントローラーとオーケストレーションを管理します（管理者専用、実験的）
• glab-ci — CI/CD パイプラインとジョブを表示および管理します
• glab-job — 個別のジョブを再試行、キャンセルし、トレースログを確認します

コマンドリファレンス

glab runner <command> [--flags]

Commands:
  assign    Assign a runner to a project
  delete    Delete a runner
  jobs      List jobs processed by a runner
  list      Get a list of runners available to the user
  managers  List runner managers
  unassign  Unassign a runner from a project
  update    Update runner settings, including pause/unpause

Flags (list):
  --instance     List all runners available to the user (instance scope)
  --output       Format output as: text, json
  --page         Page number
  --per-page     Number of items per page
  --repo         Select a repository
  -h, --help     Show help