GitLab Runnerを始める

(トップページはこちら)

GitLab Runnerは、CI/CDジョブを実行するための基盤となるアプリケーションです。本記事では、GitLab Runnerの導入から運用までの全体像を、実践的な観点から解説します。

1. GitLab Runnerとは

GitLab Runnerは、CI/CDパイプラインのジョブを実際に実行するアプリケーションです。GitLab Runnerの管理は、CI/CD実行基盤のライフサイクル全体を包含します。具体的には、Runnerのデプロイと登録、ワークロードに応じたExecutorの設定、組織の成長に合わせた容量のスケーリングが含まれます。

Runner管理は、GitLabの開発ワークフロー全体の中で、検証(Verify)フェーズに位置づけられます。

Runnerへのアクセスは、スコープとタグを通じて管理し、パフォーマンスを監視しながら、Runner群全体を維持していきます。

2. Runnerのインストール

最初のステップは、GitLab Runnerアプリケーションのインストールです。インストールプロセスは、対象となるオペレーティングシステムによって異なります。

2.1. 対応プラットフォーム

GitLabは、以下のプラットフォーム向けにバイナリとインストール手順を提供しています。

• Linux: 最も一般的な選択肢。Docker Executorとの組み合わせが推奨されます
• Windows: .NETアプリケーションやPowerShellスクリプトの実行に適しています
• macOS: iOSアプリケーションのビルドに必要です
• z/OS: メインフレーム環境での実行に対応しています

インストールは、ターゲットインフラストラクチャにGitLab Runnerをダウンロードし、セットアップする作業です。プラットフォームと要件に基づいて、適切なインストール方法を選択してください。

2.2. インストール後の確認

インストールが完了したら、以下のコマンドでバージョンを確認します。

gitlab-runner --version

正常にインストールされていれば、バージョン情報が表示されます。

詳細はこちら

3. Runnerの登録

Runnerをインストールしたら、次は登録作業です。登録により、GitLabインスタンスとGitLab Runnerがインストールされたマシン間で、認証された通信が確立されます。

3.1. 登録の仕組み

登録では、認証トークンを使用して個々のRunnerをGitLabインスタンスに接続します。登録時には、Runnerのスコープ、Executorタイプ、その他の設定パラメータを指定し、Runnerの動作方法を決定します。

3.2. Runnerのスコープを決める

登録前に、Runnerを特定のGitLabグループやプロジェクトに限定するかどうかを決定する必要があります。セルフマネージドRunnerは、登録時に異なるアクセススコープで設定でき、どのプロジェクトで利用可能かを決定します。

スコープ	利用範囲	推奨される用途
インスタンスRunner	GitLabインスタンス上のすべてのプロジェクト	共通的なビルド環境、汎用的なテスト実行
グループRunner	特定のグループとそのサブグループ内のすべてのプロジェクト	チームや部門単位での専用環境、共有リソース
プロジェクトRunner	特定のプロジェクトのみ	特殊な環境要件、セキュリティ要件が高いプロジェクト

選択の判断基準

• セキュリティ要件が高い場合: プロジェクトRunnerを選択し、実行環境を完全に分離します
• リソースを効率的に共有したい場合: グループRunnerを選択し、チーム内で共有します
• 汎用的な実行環境で十分な場合: インスタンスRunnerを選択し、管理コストを削減します

3.3. タグによるジョブのルーティング

Runnerを登録する際は、タグを追加してジョブを適切なRunnerにルーティングします。意味のあるタグを割り当て、.gitlab-ci.ymlファイルでそれらを参照することで、必要な機能を持つRunnerでジョブが実行されることを保証します。

タグの命名規則例

# 環境ベース
- linux
- windows
- macos

# 機能ベース
- docker
- kubernetes
- shell

# 用途ベース
- build
- test
- deploy

# リソースベース
- high-memory
- gpu
- ssd

実際の使用例

.gitlab-ci.ymlでタグを指定してRunnerを選択します。

# Dockerが使えるLinux環境でビルドを実行
build-job:
  tags:
    - linux
    - docker
  script:
    - docker build -t myapp:latest .

# Windows環境でテストを実行
test-windows:
  tags:
    - windows
    - shell
  script:
    - .\run-tests.ps1

# 高メモリ環境でデプロイを実行
deploy-production:
  tags:
    - linux
    - high-memory
    - deploy
  script:
    - ./deploy.sh production

CI/CDジョブが実行される際、割り当てられたタグを見て、どのRunnerを使用するかを判断します。タグは、ジョブに対して利用可能なRunnerのリストをフィルタリングする唯一の方法です。

詳細はこちら

4. Executorの選択

GitLab Runner Executorは、GitLab RunnerがCI/CDジョブを実行するために使用できる、さまざまな環境と方法を指します。Executorは、パイプラインジョブが実際にどこで、どのように実行されるかを決定します。適切な設定により、ジョブが適切な環境で正しいセキュリティ境界を持って実行されることが保証されます。

4.1. 主要なExecutorの比較

Executor	実行環境	分離レベル	推奨される用途
Shell	ホストマシン上で直接実行	低	シンプルなスクリプト、ホストツールの利用
Docker	Dockerコンテナ内で実行	中	一般的なビルド・テスト、再現性の高い環境
Docker Machine	動的に作成されるDockerホスト	高	オートスケーリング、クラウド環境
Kubernetes	Kubernetesポッド内で実行	高	コンテナオーケストレーション、大規模環境
VirtualBox	仮想マシン内で実行	高	完全な分離が必要な場合

4.2. Executorの選択基準

Shell Executorを選ぶ場合

• ホストマシンに既にインストールされているツールを使いたい
• セットアップが簡単で、すぐに始めたい
• ジョブ間の分離が不要

Docker Executorを選ぶ場合（最も推奨）

• 各ジョブを独立した環境で実行したい
• 異なるバージョンの言語やツールを使い分けたい
• 再現性の高いビルド環境が必要

Kubernetes Executorを選ぶ場合

• 既にKubernetesクラスタを運用している
• 大規模なジョブ実行が必要
• リソースの効率的な利用が重要

4.3. 実践的な設定例

例1: PowerShellコマンドの実行（Shell Executor）

WindowsサーバーにGitLab Runnerをインストールし、Shell Executorを使用するRunnerを登録します。

# Runner登録コマンド
gitlab-runner register `
  --non-interactive `
  --url "https://gitlab.com/" `
  --registration-token "YOUR_TOKEN" `
  --executor "shell" `
  --description "windows-shell-runner" `
  --tag-list "windows,shell,powershell"

例2: カスタムDockerコンテナでの実行（Docker Executor）

LinuxサーバーにGitLab Runnerをインストールし、Docker Executorを使用するRunnerを登録します。

# Runner登録コマンド
gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "YOUR_TOKEN" \
  --executor "docker" \
  --docker-image "ruby:3.2" \
  --description "docker-runner" \
  --tag-list "linux,docker"

これらの例は、可能な設定のほんの一部です。仮想マシンにGitLab Runnerをインストールし、別の仮想マシンをExecutorとして使用することもできます。

詳細はこちら

5. Runnerの設定とジョブの実行開始

GitLab Runnerは、config.tomlファイルを編集することで設定できます。このファイルは、Runnerをインストールして登録すると自動的に生成されます。

5.1. config.tomlの構造

config.tomlファイルは、グローバル設定とRunner固有の設定で構成されます。

# グローバル設定
concurrent = 4  # 同時実行可能なジョブ数
check_interval = 0  # 新しいジョブをチェックする間隔（秒）

# セッションサーバー設定（デバッグ用）
[session_server]
  session_timeout = 1800

# Runner固有の設定
[[runners]]
  name = "docker-runner"
  url = "https://gitlab.com/"
  token = "YOUR_RUNNER_TOKEN"
  executor = "docker"
  
  # Docker Executor固有の設定
  [runners.docker]
    tls_verify = false
    image = "ruby:3.2"
    privileged = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0
  
  # キャッシュ設定
  [runners.cache]
    Type = "s3"
    Shared = true
    [runners.cache.s3]
      ServerAddress = "s3.amazonaws.com"
      BucketName = "runner-cache"
      BucketLocation = "ap-northeast-1"

5.2. 重要な設定パラメータ

同時実行数の設定

concurrentパラメータは、Runner全体で同時に実行できるジョブの最大数を指定します。

concurrent = 4  # 推奨: CPUコア数と同じか、その2倍程度

判断基準

• CPUコア数が4の場合: concurrent = 4 または 8
• メモリが潤沢な場合: より高い値を設定可能
• I/O負荷が高い場合: CPUコア数より少なめに設定

ログレベルの設定

トラブルシューティング時には、ログレベルを調整します。

log_level = "info"  # debug, info, warn, error, fatal, panic
log_format = "text"  # text または json

キャッシュ設定

ビルド時間を短縮するため、依存関係をキャッシュします。

[[runners]]
  [runners.cache]
    Type = "s3"  # s3, gcs, azure
    Shared = true  # 複数のRunnerでキャッシュを共有
    [runners.cache.s3]
      ServerAddress = "s3.amazonaws.com"
      BucketName = "runner-cache"
      BucketLocation = "ap-northeast-1"

5.3. ジョブの実行フロー

Runnerが設定され、プロジェクトで利用可能になると、CI/CDジョブがそのRunnerを使用できるようになります。

通常、RunnerはGitLab Runnerをインストールしたのと同じマシン上でジョブを処理します。ただし、コンテナ内、Kubernetesクラスタ内、またはクラウド上の自動スケールインスタンス内でジョブを処理させることもできます。

5.4. セキュリティの考慮事項

認証トークンの管理

• 登録トークンと実行トークンは厳重に管理してください
• config.tomlファイルのパーミッションを適切に設定します（chmod 600）
• トークンをバージョン管理システムにコミットしないでください

実行環境の分離

• 本番環境用のRunnerは専用のマシンで実行することを推奨します
• privilegedモードは必要な場合のみ有効化してください
• Docker Executorを使用する場合、信頼できないコードの実行には注意が必要です

詳細はこちら

6. 設定の継続、スケーリング、最適化

高度なRunner機能により、ジョブ実行の効率が向上し、複雑なCI/CDワークフローに対応する特殊な機能が提供されます。これらの最適化により、ジョブの実行時間が短縮され、オートスケーリング、パフォーマンス監視、フリート管理、特殊な設定を通じて開発者体験が向上します。

6.1. オートスケーリング

オートスケーリングは、ジョブの需要に基づいてRunner容量を自動的に調整します。パフォーマンス最適化により、効率的なリソース利用が保証されます。これらの機能により、インフラストラクチャコストを管理しながら、変動するワークロードに対応できます。

オートスケーリングの仕組み

設定例（Docker Machine使用）

[[runners]]
  [runners.machine]
    IdleCount = 2  # アイドル状態で保持するマシン数
    IdleTime = 600  # アイドル状態のマシンを削除するまでの時間（秒）
    MaxBuilds = 100  # 1つのマシンで実行する最大ビルド数
    MachineDriver = "amazonec2"  # クラウドプロバイダー
    MachineName = "gitlab-runner-%s"
    MachineOptions = [
      "amazonec2-instance-type=t3.medium",
      "amazonec2-region=ap-northeast-1",
      "amazonec2-zone=a"
    ]

6.2. フリート管理

フリート管理は、複数のRunnerに対する集中管理と監視を提供し、エンタープライズ規模のRunner展開を可能にします。フリートスケーリングには、複数のRunner間での容量調整と、運用のベストプラクティスの実装が含まれます。

フリート管理のベストプラクティス

1. Runner群の分類: 用途別にRunnerを分類し、タグで管理します
2. 負荷分散: 複数のRunnerに均等にジョブを分散させます
3. 冗長性の確保: 重要なワークロードには複数のRunnerを割り当てます
4. 定期的なメンテナンス: Runnerのバージョンアップと設定の見直しを行います

6.3. パフォーマンス監視

組み込みのPrometheusメトリクスを使用して、Runnerの健全性とパフォーマンスを監視できます。以下の主要メトリクスを追跡することで、Runnerが効率的に動作していることを確認できます。

監視すべき主要メトリクス

メトリクス	説明	推奨される閾値
アクティブなジョブ数	現在実行中のジョブ数	concurrent設定値以下
CPU使用率	Runnerマシンの CPU使用率	80%以下
メモリ使用量	Runnerマシンのメモリ使用量	85%以下
ジョブ成功率	成功したジョブの割合	95%以上
キューの長さ	待機中のジョブ数	10以下
ジョブ実行時間	ジョブの平均実行時間	プロジェクトにより異なる

Prometheusメトリクスの有効化

# config.tomlに追加
listen_address = ":9252"  # Prometheusメトリクスを公開するポート

メトリクスは http://runner-host:9252/metrics でアクセスできます。

6.4. パフォーマンスチューニングの実践例

例1: ビルド時間の短縮

キャッシュを活用して依存関係のダウンロード時間を削減します。

# .gitlab-ci.yml
build:
  tags:
    - docker
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
      - .npm/
  script:
    - npm ci --cache .npm --prefer-offline
    - npm run build

例2: 並列実行の活用

テストを並列実行して全体の実行時間を短縮します。

# .gitlab-ci.yml
test:
  tags:
    - docker
  parallel: 4  # 4つのジョブに分割
  script:
    - npm run test -- --shard=${CI_NODE_INDEX}/${CI_NODE_TOTAL}

例3: リソース制限の設定

Dockerコンテナのリソース使用量を制限します。

# config.toml
[[runners]]
  [runners.docker]
    cpus = "2"  # CPU数の制限
    memory = "4g"  # メモリの制限
    memory_swap = "4g"  # スワップメモリの制限

6.5. トラブルシューティング

よくある問題と解決方法

問題1: Runnerがジョブを取得しない

原因:

• ネットワーク接続の問題
• 認証トークンの期限切れ
• タグのミスマッチ

解決方法:

# Runnerの状態確認
gitlab-runner verify

# Runnerの再起動
gitlab-runner restart

# ログの確認
gitlab-runner --debug run

問題2: ジョブが頻繁に失敗する

原因:

• リソース不足（メモリ、ディスク容量）
• タイムアウト設定が短すぎる
• 依存関係の問題

解決方法:

# config.tomlでタイムアウトを延長
[[runners]]
  [runners.docker]
    wait_for_services_timeout = 300  # サービス起動待機時間（秒）

問題3: キャッシュが機能しない

原因:

• キャッシュキーの設定ミス
• キャッシュストレージの容量不足
• ネットワークの問題

解決方法:

# .gitlab-ci.ymlでキャッシュキーを確認
cache:
  key: ${CI_COMMIT_REF_SLUG}  # ブランチごとにキャッシュ
  paths:
    - node_modules/
  policy: pull-push  # 明示的にpull-pushを指定

詳細はこちら

7. まとめ

GitLab Runnerの管理は、インストールから始まり、登録、Executorの選択、設定、そして継続的な最適化へと進みます。各ステップで適切な判断を行うことで、効率的で拡張性のあるCI/CD実行基盤を構築できます。

成功のためのポイント

1. 段階的な導入: 小規模なプロジェクトから始めて、徐々に拡大していきます
2. 適切なスコープ選択: セキュリティ要件とリソース効率のバランスを考慮します
3. タグの戦略的な使用: 明確な命名規則でRunnerを効率的に管理します
4. 継続的な監視: メトリクスを活用して問題を早期に発見します
5. 定期的な最適化: パフォーマンスデータに基づいて設定を調整します

小規模なプロジェクトから始めて、組織の成長に合わせてRunner群をスケールさせていくアプローチが実践的です。監視とメトリクスを活用しながら、継続的に改善を重ねることで、開発チームの生産性を最大化できます。