初心者向けGitLab Runner解説：導入から活用まで

By /

初心者向けGitLab Runner解説：導入から活用まで

ソフトウェア開発において、継続的インテグレーション（CI）と継続的デプロイ（CD）は、開発効率と品質を劇的に向上させるための重要なプラクティスです。GitLabは、これらのCI/CDパイプラインを構築するための強力な機能を提供しており、その中心的な役割を担うのが「GitLab Runner」です。

しかし、「Runnerって何？」「どうやってインストールするの？」「どうやって使うの？」と感じている初心者の方も多いかもしれません。この記事では、GitLab Runnerの基本から、インストール、登録、設定、そして実際のCI/CDパイプラインでの活用方法まで、初心者にも分かりやすく詳細に解説します。GitLab Runnerを理解し、あなたの開発プロセスにCI/CDを取り入れるための一歩を踏み出しましょう。

1. はじめに：GitLab Runnerとは何か、なぜ重要なのか

現代のソフトウェア開発では、コードの変更があるたびに、自動的にテストを実行したり、アプリケーションをビルドしたり、本番環境にデプロイしたりすることが一般的です。この一連の自動化されたプロセスを「CI/CDパイプライン」と呼びます。

GitLabは、リポジトリ管理だけでなく、このCI/CDパイプラインを構築するための強力な機能（GitLab CI/CD）を統合して提供しています。GitLab CI/CDは、プロジェクトのルートディレクトリに置かれた.gitlab-ci.ymlというYAMLファイルで定義された指示に従って、パイプラインを実行します。

では、この.gitlab-ci.ymlに書かれた「テストを実行しろ」「ビルドしろ」「デプロイしろ」といった指示を実行するのは誰でしょうか？それが、GitLab Runnerです。

GitLab Runnerの役割:

  • GitLab CI/CDジョブの実行者: RunnerはGitLabインスタンス（GitLab.comまたはセルフホストされたGitLabサーバー）からジョブを受け取り、そのジョブに定義されたスクリプト（コマンド）を実際に実行します。
  • 様々な環境でのジョブ実行: Runnerは、物理マシン、仮想マシン、Dockerコンテナ、Kubernetesクラスタなど、様々な環境で動作させることができます。これにより、ジョブの種類や要件に合わせて最適な環境で実行できます。
  • 並列実行: 複数のRunnerをセットアップすることで、複数のジョブやパイプラインを同時に実行し、CI/CDの実行時間を短縮できます。

なぜGitLab Runnerが重要なのか？

GitLab Runnerがなければ、GitLab CI/CDパイプラインは単なる定義ファイル（.gitlab-ci.yml）に過ぎません。Runnerがいるからこそ、コードの変更をトリガーとして、自動的なテスト、ビルド、デプロイが可能になり、以下のようなメリットが得られます。

  • 品質向上: 自動テストにより、バグの早期発見と修正が可能になります。
  • 開発速度向上: 手動でのビルドやデプロイの時間を削減し、開発者はより重要なタスクに集中できます。
  • 信頼性の高いリリース: デプロイプロセスを自動化・標準化することで、人為的なミスを減らし、より頻繁で信頼性の高いリリースが可能になります。
  • 透明性: CI/CDパイプラインの実行状況や結果がGitLab上で可視化されます。

GitLab Runnerは、GitLabを使った効率的かつモダンなソフトウェア開発ワークフローにおいて、不可欠な要素と言えます。

2. GitLab CI/CDの基本

GitLab Runnerをより深く理解するために、GitLab CI/CDの基本的な仕組みについて少し触れておきましょう。

GitLab CI/CDは、プロジェクトのリポジトリにプッシュされたコード変更を検知すると、.gitlab-ci.ymlファイルを探します。このファイルには、CI/CDパイプラインを構成する「ステージ (stages)」と、各ステージで実行される「ジョブ (jobs)」が定義されています。

.gitlab-ci.ymlの例:

“`yaml
stages:
– build
– test
– deploy

build_job:
stage: build
script:
– echo “Building the application…”
– ./build.sh
tags:
– docker

test_job:
stage: test
script:
– echo “Running tests…”
– ./run_tests.sh
tags:
– docker

deploy_job:
stage: deploy
script:
– echo “Deploying to production…”
– ./deploy_prod.sh
only:
– main # Deploy only on pushes to the main branch
tags:
– deploy_server
“`

この例では、build、test、deployの3つのステージがあり、それぞれに対応するジョブが定義されています。各ジョブには実行すべきscript（コマンド）と、そのジョブを実行できるRunnerを指定するためのtagsが設定されています。

GitLab CI/CDは、この.gitlab-ci.ymlを解析し、パイプラインを構成する各ジョブをRunnerに「渡す」役割をします。RunnerはGitLabインスタンスに定期的に問い合わせ（Polling）を行い、実行可能なジョブがないか確認します。実行可能なジョブが見つかると、Runnerはそのジョブを取得し、ローカルまたは指定された環境でジョブのスクリプトを実行します。実行結果（成功/失敗、ログ、生成物など）はGitLabインスタンスに返送され、GitLabのUI上で確認できるようになります。

簡単に言えば、GitLabは何を実行するか（.gitlab-ci.yml）を定義し、Runnerは実際にその「何か」を実行する、という分担になっています。

3. GitLab Runnerとは：詳細な解説

前述の通り、GitLab RunnerはGitLab CI/CDジョブを実行するためのエージェントです。ここでは、Runnerのタイプや実行環境について詳しく見ていきましょう。

3.1 Runnerのタイプ (どこに紐づくか)

Runnerは、どのレベルでジョブを実行するかによって、いくつかのタイプに分けられます。

  • Shared Runners:

    • GitLabインスタンス全体に紐づけられ、そのインスタンス上のすべてのプロジェクトで利用可能なRunnerです。
    • 多数のプロジェクトで共通のCI/CDジョブ（例: コードのリンティング、簡単な静的解析）を実行する場合に便利です。
    • 利用者は Runner を自分でセットアップする必要がないため、特に GitLab.com を利用している場合に手軽に利用できます。
    • ただし、多数のプロジェクトが利用するため、ジョブ実行まで待機時間が発生したり、リソースが不足したりする可能性があります。また、異なるプロジェクトのジョブが同じRunner上で実行される可能性があるため、セキュリティやプライバシーの観点から注意が必要です（特にセルフホストの場合）。

  • Group Runners:

    • 特定のグループに紐づけられ、そのグループ内のすべてのプロジェクトで利用可能なRunnerです。
    • Shared RunnerとSpecific Runnerの中間に位置します。グループ内のプロジェクトで共通の要件がある場合（例: 特定の技術スタック、内部ツールへのアクセスが必要なジョブ）に、グループ全体でRunnerリソースを共有できます。
    • グループメンバーは自分でRunnerを管理する必要がありません。

  • Specific Runners:

    • 特定のプロジェクトのみに紐づけられるRunnerです。
    • プロジェクト固有の特殊な要件があるジョブ（例: 特定のハードウェアが必要なテスト、社内ネットワーク内の特定サーバーへのデプロイ）に適しています。
    • 最も細かい粒度でアクセス制御やリソース割り当てが可能です。
    • プロジェクトごとにRunnerを管理する必要があります。

初心者の方が自分のプロジェクトでCI/CDを始める場合、まずはSpecific Runnerをセットアップするのが一般的です。プロジェクトの要件に合わせて、Runnerが動作する環境を自由に選択・設定できます。

3.2 Executor (どのようにジョブを実行するか)

Runnerは、ジョブを受け取った後、実際にスクリプトを実行するための「実行環境 (Executor)」を選択します。.gitlab-ci.ymlのジョブには、どのExecutorタイプを優先的に使用するか指定するオプションはありませんが、Runner自体の設定ファイル(config.toml)で、そのRunnerがどのExecutorを使用するか、または複数のExecutorをサポートするかを指定できます。

主要なExecutorタイプは以下の通りです。

  • Shell Executor:

    • RunnerがインストールされているホストOS上で直接ジョブのスクリプトを実行します。
    • 最もシンプルで設定が容易です。
    • Runnerがインストールされているマシンに直接アクセスできる必要があります。
    • ジョブごとに環境が分離されないため、異なるジョブが同じファイルや環境設定に影響を与え合う可能性があります。セキュリティ上のリスクも考慮が必要です。

  • Docker Executor:

    • ジョブごとに新しいDockerコンテナを起動し、そのコンテナ内でスクリプトを実行します。
    • .gitlab-ci.ymlで指定されたDockerイメージ（imageキーワード）を使用してコンテナを作成します。
    • 各ジョブが独立したクリーンな環境で実行されるため、環境の再現性が高く、他のジョブとの干渉を防げます。
    • 最も一般的で推奨されるExecutorタイプです。
    • RunnerがインストールされているマシンにDockerがインストールされている必要があります。

  • Docker Machine Executor:

    • Docker Executorを拡張したもので、必要に応じて動的に仮想マシンをプロビジョニングし、その上でDockerコンテナを起動してジョブを実行します。
    • クラウドプロバイダ（AWS, GCP, Azureなど）や仮想化プラットフォーム（VirtualBox, VMwareなど）と連携し、必要に応じてRunner環境をスケールアップ/ダウンできます。
    • 大規模なプロジェクトや、ジョブの負荷が変動する場合に適していますが、設定はより複雑になります。

  • Kubernetes Executor:

    • ジョブをKubernetesクラスタ上のPodとして実行します。
    • Kubernetesの豊富な機能（スケーリング、リソース管理、分離など）を利用できます。
    • コンテナ化されたアプリケーションの開発/デプロイとの親和性が高いです。
    • Kubernetesクラスタの構築・管理に関する知識が必要です。

  • Parallels Executor:

    • macOS上でParallels Desktop仮想マシンを使用してジョブを実行します。

  • VirtualBox Executor:

    • VirtualBox仮想マシンを使用してジョブを実行します。

  • SSH Executor:

    • SSH経由でリモートサーバーに接続し、そこでジョブのスクリプトを実行します。
    • 特定のサーバーでジョブを実行する必要がある場合に利用できます。

初心者の方が Specific Runner をセットアップする場合、Shell ExecutorかDocker Executorを選択するのが一般的です。Shell Executorは最も手軽ですが、環境の分離を考えるとDocker Executorがおすすめです。Docker Executorを使う場合は、RunnerをインストールするマシンにDockerを準備する必要があります。

4. GitLab Runner導入の準備

GitLab Runnerをインストールし、GitLabインスタンスに登録するには、いくつかの準備が必要です。

4.1 システム要件

GitLab Runner自体は比較的軽量なアプリケーションですが、選択するExecutorや実行するジョブの内容によって、必要なリソースは大きく異なります。

  • OS: Linux (x86-64, arm, arm64), Windows (x86-64), macOS (x86-64, arm64) をサポートしています。あなたの環境に合わせて選択してください。
  • CPU/メモリ: Runnerプロセス自体の要件は低いですが、実行するジョブが要求するリソース（コンパイル、テスト実行、Dockerビルドなど）によって必要なスペックが決まります。複数のジョブを並列実行する場合は、さらに多くのリソースが必要です。
  • ストレージ: ジョブのクローン、キャッシュ、アーティファクトなどに使用されます。特にDocker Executorで多くのイメージを使用する場合や、大きなアーティファクトを扱う場合は、十分なディスク容量が必要です。
  • ネットワーク: GitLabインスタンスへのHTTPS接続が必要です。ファイアウォールなどで通信がブロックされていないか確認してください。
  • Executor固有の要件:
    • Docker Executor: Docker Engineがインストールされ、RunnerプロセスがDockerデーモンと通信できる必要があります。
    • Kubernetes Executor: Kubernetesクラスタへのアクセス権が必要です。

4.2 インストール方法の選択肢

GitLab Runnerのインストール方法は、OSや環境によっていくつかの選択肢があります。

  • OSネイティブパッケージ: Linuxディストリビューションのパッケージマネージャー（apt, yum, dnfなど）や、Windows/macOS向けのインストーラー/パッケージマネージャー（Chocolatey, Homebrewなど）を使用してインストールするのが最も一般的です。これにより、Runnerがサービスとして起動し、システムの起動時に自動実行されるように設定できます。
  • バイナリダウンロード: GitLabの公式サイトからRunnerの実行バイナリを直接ダウンロードし、手動で配置・実行することも可能です。サービスの登録は手動で行う必要があります。
  • Dockerコンテナ: DockerコンテナとしてRunnerを実行することもできます。Dockerが動作する環境であれば、ホストOSの種類を問わず同じ方法でインストールできます。これは特に、すでにDockerを広く利用している環境や、Kubernetesなどのコンテナオーケストレーション上でRunnerを実行したい場合に便利です。

初心者の方には、利用しているOSのネイティブパッケージを使ったインストールが推奨されます。システムサービスとして管理されるため、運用が容易です。

4.3 登録に必要な情報

Runnerをインストールした後、それを特定のGitLabインスタンス、グループ、またはプロジェクトに紐づける「登録 (Registration)」という作業が必要です。登録には以下の情報が必要です。

  • GitLabインスタンスのURL: GitLab.comを使用している場合は https://gitlab.com です。セルフホストのGitLabを使用している場合は、そのURL（例: https://your.gitlab.instance.com）です。
  • Registration Token: Runnerを登録する際に使用する使い捨てのトークンです。このトークンは、Runnerを紐づけたいレベル（インスタンス、グループ、プロジェクト）のGitLab UI上で取得できます。
    • Specific Runnerの場合: プロジェクト設定 > CI/CD > Runners にあります。
    • Group Runnerの場合: グループ設定 > CI/CD > Runners にあります。
    • Shared Runner (インスタンスレベル) の場合: 管理エリア > CI/CD > Runners にあります (GitLab管理者のみ)。
  • Executorタイプ: 前述のShell, Docker, Kubernetesなど、どのExecutorを使用するかを登録時に指定します。

これらの情報（特にRegistration Token）はRunnerを登録するためだけに使用され、その後のジョブ実行には使用されません。ジョブ実行には、登録時に生成されるRunnerトークンがGitLabインスタンスとRunner間の通信認証に使用されます。

5. GitLab Runnerのインストールと登録

それでは、具体的なRunnerのインストールと登録の手順を見ていきましょう。ここでは、一般的なOS (Linux, Windows, macOS) および Docker を使用した方法を解説します。

5.1 Linuxへのインストール (apt-get/yum/dnfを使用)

多くのLinuxディストリビューションでは、公式リポジトリからGitLab Runnerを簡単にインストールできます。

手順 (Debian/Ubuntu系):

  1. 公式リポジトリの追加:
    bash
    curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
    このスクリプトは、GitLab Runnerのパッケージリポジトリを追加し、GPGキーをインポートします。
  2. GitLab Runnerのインストール:
    bash
    sudo apt-get update
    sudo apt-get install gitlab-runner
    apt-getを使用してGitLab Runnerパッケージをインストールします。依存関係も同時にインストールされます。
  3. インストールの確認:
    bash
    gitlab-runner --version
    バージョン情報が表示されればインストール成功です。

手順 (RHEL/CentOS/Fedora系):

  1. 公式リポジトリの追加:
    bash
    curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh" | sudo bash
    このスクリプトは、GitLab Runnerのパッケージリポジトリを追加し、GPGキーをインポートします。
  2. GitLab Runnerのインストール:
    bash
    sudo yum install gitlab-runner # または sudo dnf install gitlab-runner (Fedora 22+ / CentOS 8+)
    yumまたはdnfを使用してGitLab Runnerパッケージをインストールします。
  3. インストールの確認:
    bash
    gitlab-runner --version
    バージョン情報が表示されればインストール成功です。

インストール後、GitLab Runnerサービスは自動的に起動します。sudo systemctl status gitlab-runner (systemdを使用している場合) または sudo service gitlab-runner status (SysVinitを使用している場合) で状態を確認できます。

5.2 Windowsへのインストール

Windowsでは、実行バイナリをダウンロードして手動でインストールするか、Chocolateyパッケージマネージャーを使用する方法があります。

手順 (手動インストール):

  1. バイナリのダウンロード:
    最新バージョンの実行ファイル (gitlab-runner-windows-amd64.exe) を以下のURLからダウンロードします。
    https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-windows-amd64.exe
  2. ディレクトリの作成と配置:
    Cドライブのルートなどに新しいフォルダを作成し、ダウンロードしたファイルを配置します。例: C:\GitLab-Runner
    powershell
    # PowerShell を管理者として実行
    New-Item -Path C:\GitLab-Runner -ItemType Directory
    Move-Item -Path $env:USERPROFILE\Downloads\gitlab-runner-windows-amd64.exe -Destination C:\GitLab-Runner\gitlab-runner.exe
    Set-Location -Path C:\GitLab-Runner
  3. Runnerサービスのインストールと起動:
    配置したディレクトリで、管理者権限のコマンドプロンプトまたはPowerShellを開き、以下のコマンドを実行します。
    powershell
    .\gitlab-runner.exe install # サービスとしてインストール
    .\gitlab-runner.exe start # サービスを開始
  4. インストールの確認:
    サービスが実行されているか確認します。
    powershell
    Get-Service gitlab-runner
    Stateが Running になっていれば成功です。

手順 (Chocolateyを使用):

  1. Chocolateyのインストール: Chocolateyがインストールされていない場合は、公式サイトの手順に従ってインストールします。
    https://chocolatey.org/install
  2. GitLab Runnerのインストール: 管理者権限のコマンドプロンプトまたはPowerShellを開き、以下のコマンドを実行します。
    powershell
    choco install gitlab-runner
    これにより、GitLab Runnerがインストールされ、Windowsサービスとして登録・起動されます。
  3. インストールの確認:
    powershell
    Get-Service gitlab-runner
    Stateが Running になっていれば成功です。

5.3 macOSへのインストール (Homebrewを使用)

macOSでは、Homebrewパッケージマネージャーを使用するのが最も簡単です。

手順 (Homebrewを使用):

  1. Homebrewのインストール: Homebrewがインストールされていない場合は、公式サイトの手順に従ってインストールします。
    https://brew.sh/
  2. GitLab Runnerのインストール: ターミナルを開き、以下のコマンドを実行します。
    bash
    brew install gitlab-runner
  3. Runnerサービスのインストールと起動:
    bash
    brew services start gitlab-runner
    これにより、GitLab RunnerがmacOSのLaunchAgentsサービスとして登録・起動されます。
  4. インストールの確認:
    bash
    brew services list
    リストに gitlab-runner が表示され、Statusが started になっていれば成功です。

5.4 Dockerコンテナでの実行

Dockerがインストールされている環境であれば、RunnerをDockerコンテナとして実行できます。これはホストOSに依存しない方法です。

手順:

  1. Runnerの設定ボリュームを作成 (任意だが推奨): Runnerの設定やキャッシュを永続化するためのボリュームを作成します。
    bash
    docker volume create gitlab-runner-config

  2. Runnerコンテナを実行: 以下のコマンドでGitLab Runnerコンテナを実行します。先ほど作成したボリュームをマウントします。
    bash
    docker run -d --name gitlab-runner --restart always \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v gitlab-runner-config:/etc/gitlab-runner \
    gitlab/gitlab-runner:latest

    • -d: デタッチドモード（バックグラウンド）で実行します。
    • --name gitlab-runner: コンテナに gitlab-runner という名前を付けます。
    • --restart always: Dockerデーモン再起動時にコンテナも常に再起動するように設定します。
    • -v /var/run/docker.sock:/var/run/docker.sock: ホストのDockerデーモンソケットをコンテナ内にマウントします。これは、コンテナ内でDockerコマンドを実行する (つまり、Docker Executorを使用する) ために必要です。Shell ExecutorなどDockerを使わない場合は不要です。
    • -v gitlab-runner-config:/etc/gitlab-runner: Runnerの設定ファイル(config.toml)が保存されるディレクトリをボリュームにマウントします。
    • gitlab/gitlab-runner:latest: 使用するGitLab RunnerのDockerイメージです。latestタグは最新版を取得しますが、特定のバージョンを指定することをおすすめします。

  3. インストールの確認:
    bash
    docker ps
    gitlab-runnerという名前のコンテナが Up の状態になっているか確認します。

Dockerコンテナとして実行した場合、Runnerの操作（登録、実行、停止など）は、docker exec コマンドを使ってコンテナ内でRunnerコマンドを実行することで行います。

5.5 Runnerの登録 (gitlab-runner register)

Runnerをインストールしたら、GitLabインスタンスに登録して使えるようにします。この作業は、どのインストール方法を選んだ場合でも基本的に同じコマンドで行います。

  1. GitLabインスタンスでRegistration Tokenを取得:

    • プロジェクトの特定Runnerとして登録する場合: 対象プロジェクトを開き、「Settings」->「CI/CD」->「Runners」セクションを探します。「Specific runners」の項目に表示されているURLとトークンを控えておきます。
    • グループのRunnerとして登録する場合: 対象グループを開き、「Settings」->「CI/CD」->「Runners」セクションを探します。「Group runners」の項目に表示されているURLとトークンを控えておきます。
    • インスタンスのShared Runnerとして登録する場合: GitLabの管理エリア（Admin Area）を開き、「CI/CD」->「Runners」セクションを探します。「Shared runners」の項目に表示されているURLとトークンを控えておきます。これは管理者権限が必要です。

  2. 登録コマンドの実行:
    Runnerがインストールされているマシンで、ターミナルまたはコマンドプロンプトを開き、以下のコマンドを実行します。

    • Linux/macOS (システムインストール):
      bash
      sudo gitlab-runner register
    • Windows (手動インストール):
      powershell
      C:\GitLab-Runner\gitlab-runner.exe register
    • Windows (Chocolatey):
      powershell
      gitlab-runner register
    • Dockerコンテナ:
      bash
      docker exec -it gitlab-runner gitlab-runner register
      -it オプションは、インタラクティブな操作のために必要です。

  3. 対話式プロンプトへの応答:
    gitlab-runner register コマンドを実行すると、いくつかの情報を対話形式で入力するよう求められます。

    • Enter your GitLab instance URL:
      • 手順1で控えたGitLabインスタンスのURLを入力します。（例: https://gitlab.com/ または https://your.gitlab.instance.com/）
    • Enter the registration token:
      • 手順1で控えたRegistration Tokenを入力します。
    • Enter a description for the runner:
      • このRunnerの説明を入力します。GitLab UIでRunnerを識別する際に表示される名前になります。後から変更可能です。（例: My Project Docker Runner）
    • Enter tags for the runner (comma-separated):
      • このRunnerに紐づけるタグを入力します。複数のタグを指定する場合はカンマで区切ります。タグは、.gitlab-ci.ymlで特定のジョブをこのRunnerで実行させたい場合に指定します。後から変更可能です。（例: docker, build, test）
      • タグは非常に重要です。 ジョブがどのRunnerで実行されるかを制御するために使われます。特定のRunnerだけで実行したいジョブがある場合は、そのジョブとRunnerの両方に同じタグを設定します。タグを指定しないRunnerは、タグが指定されていないジョブを実行します。
    • Enter the executor: shell, docker, kubernetes, etc.:
      • 使用するExecutorタイプを入力します。（例: docker または shell）
    • (Executor固有の設定): 選択したExecutorによっては、追加の設定を求められます。
      • docker を選択した場合: Enter the default Docker image (for example, ruby:2.5): – ジョブの.gitlab-ci.ymlでimageが指定されていない場合にデフォルトで使用されるDockerイメージを指定します。（例: ubuntu:latest）

    すべての入力を終えると、RunnerがGitLabインスタンスに登録され、設定ファイル(config.toml)が生成または更新されます。

  4. 登録の確認:
    GitLab UIに戻り、「Settings」->「CI/CD」->「Runners」セクションを確認します。登録したRunnerが「Specific runners」または「Group runners」や「Shared runners」のリストに表示され、ステータスが緑色の丸で「Online」または「Idle」になっていれば登録成功です。

5.6 複数のRunnerを登録する

必要に応じて、1台のマシンに複数のRunnerをインストール・登録することも可能です。例えば、Shell ExecutorのRunnerとDocker ExecutorのRunnerを同じマシン上で動作させることができます。

gitlab-runner register コマンドを再度実行し、異なるDescription、Tags、Executorなどで登録を行います。それぞれの登録情報が config.toml ファイルに追加されます。

6. GitLab Runnerの設定 (config.toml)

Runnerの動作は、設定ファイル config.toml で細かく制御できます。登録時に基本的な設定は行われますが、さらに詳細な設定を行うことで、Runnerの性能や動作を最適化できます。

config.toml ファイルの場所は、インストール方法によって異なります。

  • Linux/macOS (システムインストール): /etc/gitlab-runner/config.toml
  • Windows (手動インストール): Runnerのインストールディレクトリ（例: C:\GitLab-Runner）内の config.toml
  • Windows (Chocolatey): C:\ProgramData\GitLab-Runner ディレクトリ内の config.toml
  • Dockerコンテナ: Dockerボリュームまたはバインドマウントしたディレクトリ（例: gitlab-runner-config ボリューム）内の /etc/gitlab-runner/config.toml

ファイルを編集する際は、適切な権限（Linux/macOSの場合は sudo）が必要です。

config.toml の基本的な構造は以下のようになります。

“`toml
concurrent = 1 # 同時に実行できるジョブの最大数
check_interval = 0 # GitLabへのジョブ問い合わせ間隔 (秒)

[[runners]] # Runnerの設定ブロック (複数登録している場合はこのブロックが複数あります)
name = “My Project Docker Runner” # Runnerの名前 (Description)
url = “https://gitlab.com/” # GitLabインスタンスのURL
token = “YOUR_RUNNER_TOKEN” # Runnerの認証トークン (登録時に自動生成)
executor = “docker” # 使用するExecutorタイプ
[runners.docker] # Docker Executor の設定 (Executor に応じて設定ブロックが変わります)
image = “ubuntu:latest” # デフォルトのDockerイメージ
privileged = false # コンテナ特権モードの有効/無効
disable_entrypoint_overwrite = false
oom_kill_disable = false
disable_cache = false
volumes = [“/cache”] # キャッシュに使用するボリューム
shm_size = 0
[runners.cache] # キャッシュ設定
[runners.cache.s3]
[runners.cache.gcs]
“`

重要な設定項目:

  • concurrent:
    • この設定ファイルによって管理されるすべてのRunnerで、同時に実行できるジョブの合計数を指定します。
    • マシンのCPU、メモリ、ディスク容量を考慮して設定します。例えば、concurrent = 4 なら、最大4つのジョブが同時に実行されます。
  • check_interval:
    • Runnerが新しいジョブがないかGitLabインスタンスに問い合わせる間隔を秒単位で指定します。デフォルトは0で、これはほぼ即座に問い合わせることを意味しますが、GitLabサーバーへの負荷を考慮して適切な値を設定することもできます（通常はデフォルトで問題ありません）。
  • [[runners]]:
    • これはRunnerごとの設定を定義する配列です。gitlab-runner register コマンドでRunnerを登録するたびに、このブロックが1つ追加されます。
    • name: 登録時に入力した説明です。
    • url: 登録時に入力したGitLab URLです。
    • token: RunnerがGitLabと通信する際に使用する認証トークンです。これはRegistration Tokenとは異なります。登録時に自動生成され、GitLab UIでも確認できます。機密情報なので取り扱いに注意してください。
    • executor: このRunnerが使用するExecutorタイプです。
    • タグや他の設定は、この [[runners]] ブロックの中に追加されます。例えば、タグは tags = ["docker", "build"] のように定義されます。

Executor固有の設定 (例: Docker Executor [runners.docker]):

  • image: .gitlab-ci.ymlでimageが指定されていない場合にデフォルトで使用されるDockerイメージです。
  • privileged: コンテナを特権モードで実行するかどうか。特定のジョブ（例: Dockerイメージのビルド）で必要な場合がありますが、セキュリティリスクが高まるため、必要な場合以外はfalseに設定します。
  • volumes: コンテナにマウントするボリュームを指定します。キャッシュディレクトリ（/cache）はデフォルトで設定されることが多いですが、他のディレクトリをマウントしたい場合に指定します。
  • shm_size: /dev/shm のサイズを指定します。大きなプロジェクトのコンパイルなどでメモリ不足になる場合に調整が必要なことがあります。

config.toml を編集した後は、Runnerサービスを再起動して設定を反映させる必要があります。

  • Linux/macOS (システムインストール): sudo gitlab-runner restart または sudo systemctl restart gitlab-runner (systemd)
  • Windows (手動インストール): C:\GitLab-Runner\gitlab-runner.exe restart
  • Windows (Chocolatey): gitlab-runner restart
  • Dockerコンテナ: docker restart gitlab-runner

7. GitLab Runnerの管理と運用

GitLab Runnerを安定して運用するためには、起動・停止、バージョンアップ、監視、トラブルシューティングなどの基本的な管理方法を知っておくことが重要です。

7.1 Runnerの起動、停止、再起動

Runnerサービスは、インストール時に自動的に起動するように設定されることが多いですが、手動で操作する必要がある場合もあります。

  • Linux/macOS (システムインストール):

    • 起動: sudo gitlab-runner start または sudo systemctl start gitlab-runner
    • 停止: sudo gitlab-runner stop または sudo systemctl stop gitlab-runner
    • 再起動: sudo gitlab-runner restart または sudo systemctl restart gitlab-runner
    • ステータス確認: sudo gitlab-runner status または sudo systemctl status gitlab-runner

  • Windows (手動インストール):

    • 起動: C:\GitLab-Runner\gitlab-runner.exe start または Servicesアプリから操作
    • 停止: C:\GitLab-Runner\gitlab-runner.exe stop または Servicesアプリから操作
    • 再起動: C:\GitLab-Runner\gitlab-runner.exe restart または Servicesアプリから操作
    • ステータス確認: C:\GitLab-Runner\gitlab-runner.exe status または Servicesアプリから操作

  • Windows (Chocolatey):

    • コマンドは手動インストールと同じです。C:\ProgramData\GitLab-Runner\gitlab-runner.exe を実行するか、システムパスが通っていれば gitlab-runner コマンドを使用します。Servicesアプリからの操作も可能です。

  • Dockerコンテナ:

    • 起動: docker start gitlab-runner
    • 停止: docker stop gitlab-runner
    • 再起動: docker restart gitlab-runner
    • ステータス確認: docker ps -a

7.2 Runnerのバージョンアップ

GitLab Runnerは定期的に新しいバージョンがリリースされ、機能改善やバグ修正、セキュリティパッチが含まれています。GitLabインスタンスのバージョンとRunnerのバージョンを一致させるか、RunnerのバージョンをGitLabインスタンスより新しく保つことが推奨されています。

バージョンアップの手順は、インストール方法によって異なります。

  • Linux (パッケージマネージャー):
    通常通りパッケージをアップデートします。
    “`bash
    # Debian/Ubuntu系
    sudo apt-get update
    sudo apt-get upgrade gitlab-runner

    RHEL/CentOS/Fedora系

    sudo yum update gitlab-runner # または sudo dnf update gitlab-runner
    “`
    アップデート後にサービスが自動的に再起動されない場合は、手動で再起動します。

  • Windows (手動インストール):

    1. Runnerサービスを停止します (gitlab-runner stop)。
    2. 新しいバージョンの実行バイナリをダウンロードします。
    3. 既存の実行バイナリを新しいものに置き換えます。
    4. Runnerサービスを開始します (gitlab-runner start)。

  • Windows (Chocolatey):
    powershell
    choco upgrade gitlab-runner
    サービスの停止・開始は自動的に行われます。

  • macOS (Homebrew):
    bash
    brew upgrade gitlab-runner
    brew services restart gitlab-runner

  • Dockerコンテナ:

    1. 既存のRunnerコンテナを停止し、削除します。
      bash
      docker stop gitlab-runner
      docker rm gitlab-runner
    2. 最新版のイメージをプルします。
      bash
      docker pull gitlab/gitlab-runner:latest # または特定のバージョンタグ
    3. 新しいイメージでコンテナを実行します（登録情報はボリュームに保存されているため引き継がれます）。
      bash
      docker run -d --name gitlab-runner --restart always \
      -v /var/run/docker.sock:/var/run/docker.sock \
      -v gitlab-runner-config:/etc/gitlab-runner \
      gitlab/gitlab-runner:latest # 使用するイメージタグをlatestまたは指定バージョンにする

7.3 Runnerの監視

Runnerが正常に動作しているか、ジョブを処理できているかを監視することは重要です。

  • GitLab UI: GitLabインスタンスの「Admin Area」->「CI/CD」->「Runners」 (またはプロジェクト/グループ設定のRunner画面) で、登録されているRunnerのリスト、ステータス（Online/Offline/Idle/Running）、最終接続時間、処理中のジョブ数などを確認できます。
  • Runnerログ: Runnerのログファイルを確認することで、GitLabインスタンスとの通信状況、ジョブの取得・実行状況、エラーメッセージなどを詳細に把握できます。ログファイルの場所はインストール方法やOSによって異なります（例: Linuxでは /var/log/gitlab-runner/runner.log）。Dockerコンテナの場合は docker logs gitlab-runner でログを確認できます。
  • システム監視ツール: Runnerが動作しているホストマシンのリソース使用率（CPU, メモリ, ディスク, ネットワーク）を、システムの監視ツール（Nagios, Prometheus, Datadogなど）で監視します。リソース不足はジョブの遅延や失敗の原因となります。

7.4 トラブルシューティングの基本

Runner関連で問題が発生した場合の基本的なトラブルシューティング手順です。

  1. GitLab UIでRunnerの状態を確認: まず、GitLab UI上でRunnerが「Online」になっているか確認します。Offlineになっている場合は、Runnerサービスが起動していないか、GitLabインスタンスと通信できていない可能性があります。
  2. Runnerサービスの状態を確認: Runnerが動作しているマシンで、Runnerサービスが正常に起動しているか確認します（systemctl status gitlab-runner, Get-Service gitlab-runner, docker ps など）。
  3. Runnerログを確認: Runnerのログファイルを調べます。GitLabへの接続エラー、ジョブの取得エラー、スクリプト実行時のエラーなど、問題の原因を示す情報が含まれていることが多いです。
  4. config.toml の設定を確認: 設定ファイルの内容に間違いがないか確認します。特にGitLab URL、トークン、Executor設定などが正しいか見直します。設定変更後はサービスの再起動を忘れずに行います。
  5. ネットワーク接続を確認: RunnerがGitLabインスタンスにアクセスできるか、必要なポートが開いているか確認します。curl <GitLab URL>/api/v4/version などのコマンドで疎通確認ができます。
  6. Executorに関連する問題: 特定のExecutor（例: Docker）で問題が発生する場合は、そのExecutorに関連する環境（例: Dockerデーモン、Kubernetesクラスタ）が正常に動作しているか確認します。Docker Executorの場合は、RunnerがDockerデーモンと通信できているか（docker versionをRunnerマシンで実行）、指定したDockerイメージが存在するかなども確認します。
  7. 特定のジョブでのみ発生する場合: 問題が特定のジョブでのみ発生する場合は、.gitlab-ci.yml のそのジョブの定義（特にscriptブロックの内容、使用しているDockerイメージ、タグ）に問題がないか確認します。

8. Runnerの活用例 (CI/CDパイプラインとの連携)

GitLab Runnerがセットアップできたら、いよいよ .gitlab-ci.yml ファイルと連携させてCI/CDパイプラインを実行します。

8.1 .gitlab-ci.yml でのRunnerの指定方法

.gitlab-ci.yml で、特定のジョブを特定のRunnerで実行させたい場合、主に以下の方法があります。

  • tags キーワード: ジョブに tags キーワードでタグを指定します。
    yaml
    build_job:
    stage: build
    script:
    - echo "Building..."
    tags:
    - docker # このタグを持つRunnerで実行
    - linux # さらにこのタグも持つRunnerが必要
    Runnerは、ジョブに指定されたすべてのタグを持っている場合にそのジョブを実行できます。登録時にRunnerに適切なタグを設定しておくことが重要です。Specific Runnerを特定のプロジェクトのためにセットアップした場合でも、明示的にタグを設定・指定することをお勧めします。

  • runner_type キーワード (非推奨): 以前は runner_type: specific のように指定できましたが、現在は非推奨です。タグを使用してRunnerを制御するのが現在の標準的な方法です。

タグが指定されていないジョブは、タグが設定されていないRunnerか、または共有Runner（Shared RunnerやGroup Runner）によって実行される可能性があります。

8.2 Executorごとの .gitlab-ci.yml の書き方の違い

選択したExecutorによって、.gitlab-ci.yml の書き方に影響が出ることがあります。

  • Shell Executor:
    スクリプトはRunnerが動作しているホストOSのシェルで直接実行されます。システムにインストールされているツールや環境変数を利用できます。環境の分離が少ないため、ジョブ間で競合が発生しないように注意が必要です。

    yaml
    my_shell_job:
    stage: test
    script:
    - echo "Running on shell executor"
    - pwd # ホストOS上のカレントディレクトリが表示される
    - ls -l
    tags:
    - shell_runner
    Shell Executorを使用する場合、ジョブが必要とするすべての依存関係（コンパイラ、ライブラリ、ツールなど）がRunnerが動作するホストOSにインストールされている必要があります。

  • Docker Executor:
    ジョブは指定されたDockerイメージから起動されるコンテナ内で実行されます。.gitlab-ci.yml の image キーワードで、そのジョブを実行するコンテナのベースイメージを指定できます。

    yaml
    my_docker_job:
    stage: test
    image: python:3.9-slim # このジョブはpython:3.9-slimコンテナで実行される
    script:
    - echo "Running on docker executor"
    - pwd # コンテナ内のワーキングディレクトリが表示される (/builds/...)
    - python --version
    - pip install -r requirements.txt
    - pytest
    tags:
    - docker_runner
    Docker Executorを使用する場合、ジョブが必要とするすべての依存関係は、指定するDockerイメージに含まれているか、ジョブのスクリプト内でインストールする必要があります。これにより、環境の再現性と分離が向上します。

8.3 具体的なパイプライン例におけるRunnerの役割

簡単なWebアプリケーション（例えばPython/Flask）を例に、RunnerがCI/CDパイプラインでどのように機能するかを見てみましょう。

.gitlab-ci.yml 例:

“`yaml
stages:
– test
– build
– deploy

variables:
DOCKER_DRIVER: overlay2 # Docker Executorでよく使われる変数

test_app:
stage: test
image: python:3.9-slim
script:
– echo “Running tests…”
– pip install -r requirements.txt
– pytest tests/
tags:
– docker_runner # Docker Executorを持つRunnerで実行
cache:
paths:
– .cache/pip # pipインストールしたライブラリをキャッシュ

build_image:
stage: build
image: docker:latest # Dockerビルドにはdockerイメージが必要
services:
– docker:dind # Docker inside Docker (コンテナ内でDockerデーモンを動かす)
script:
– echo “Building Docker image…”
– docker build -t my-web-app:$CI_COMMIT_SHA .
– docker push my-web-app:$CI_COMMIT_SHA
tags:
– docker_runner # Docker Executorを持つRunnerで実行
only:
– main # mainブランチへのプッシュでのみ実行

deploy_prod:
stage: deploy
image: ubuntu:latest # デプロイツールがインストールされたイメージなど
script:
– echo “Deploying to production server…”
– apt-get update && apt-get install -y sshpass # デプロイに必要なツールをインストール
– sshpass -e ssh [email protected] “docker pull my-web-app:$CI_COMMIT_SHA && docker stop my-web-app || true && docker run -d –rm –name my-web-app -p 80:5000 my-web-app:$CI_COMMIT_SHA” # リモートでデプロイコマンド実行
tags:
– deploy_server_runner # デプロイ権限を持つ特定のRunnerで実行
only:
– main
when: manual # 手動実行ジョブにする
“`

このパイプラインでは、以下のようにRunnerが使われます。

  1. test_app ジョブ:

    • tags: docker_runner を持つ Docker Executor の Runner がこのジョブを取得します。
    • Runnerは python:3.9-slim イメージのコンテナを起動します。
    • コンテナ内で script に書かれたコマンド（pip install, pytest）が実行されます。
    • テスト結果がRunnerからGitLabに報告されます。
    • cache 設定により、pip install したライブラリは Runner マシン上のキャッシュ領域に保存され、次回同じRunnerがこのジョブを実行する際に再利用されます。

  2. build_image ジョブ:

    • tags: docker_runner を持つ Docker Executor の Runner がこのジョブを取得します。
    • Runnerは docker:latest イメージのコンテナを起動します。
    • さらに services: - docker:dind の指定により、もう一つ docker:dind イメージのコンテナが起動され、これがDockerデーモンとして振る舞います。build_image コンテナは、このサービスコンテナと連携してDockerコマンドを実行します。
    • コンテナ内で docker build と docker push コマンドが実行され、Dockerイメージがビルド・プッシュされます。$CI_COMMIT_SHA のようなCI/CD変数もRunnerによって提供され、スクリプト内で利用できます。

  3. deploy_prod ジョブ:

    • tags: deploy_server_runner を持つ Runner がこのジョブを実行します。このRunnerは、デプロイ先のサーバーにSSHで接続できる権限を持つマシンにセットアップされている必要があります。ExecutorはShellでもDockerでも考えられますが、例ではubuntu:latestイメージを使うDocker Executorを想定しています。
    • Runnerはデプロイ先のサーバーにSSHで接続し、Dockerイメージをプルして新しいコンテナを起動するコマンドを実行します。

このように、Runnerは .gitlab-ci.yml の定義に基づいて、適切な実行環境（コンテナ、ホストOSなど）を準備し、そこに書かれたコマンドを忠実に実行することで、CI/CDパイプラインを自動化します。どのRunnerがどのジョブを実行するかは、主にタグによって制御されます。

9. 高度な活用

GitLab RunnerとCI/CDをさらに効果的に使うための高度な機能について簡単に触れます。

  • Cacheの利用:
    依存関係のインストール（例: npm install, pip install, mvn install）は時間がかかります。cache キーワードを.gitlab-ci.ymlで使用すると、ジョブの実行環境から指定されたディレクトリをRunnerマシン上のキャッシュ領域に保存し、次回のジョブ実行時に復元できます。これにより、依存関係の再インストールにかかる時間を大幅に短縮できます。キャッシュは同じRunnerや同じタグを持つRunner間で共有できます。

  • Artifactsの利用:
    ビルド生成物（実行ファイル、Dockerイメージ、テストレポートなど）を次のステージのジョブで使用したり、ユーザーがダウンロードできるようにしたい場合があります。artifacts キーワードを.gitlab-ci.ymlで使用すると、ジョブの実行で生成されたファイルをGitLabにアップロードして保存できます。

  • サービスコンテナ (Docker Executor):
    テスト実行中にデータベースや他のサービスが必要な場合があります。Docker Executorでは、services キーワードを使用して、ジョブコンテナと一緒にサービスコンテナを起動できます。これらのサービスコンテナは、ジョブコンテナからネットワーク経由でアクセス可能です（サービス名がホスト名として解決されます）。これはテスト環境の構築に非常に便利です。

  • カスタムExecutor:
    GitLab RunnerはカスタムExecutorを定義することも可能です。これは、独自の仮想化技術を使いたい場合や、特殊な実行環境が必要な場合に利用します。ただし、設定は非常に複雑になります。

これらの機能を使うことで、CI/CDパイプラインの効率、信頼性、機能性をさらに向上させることができます。

10. セキュリティに関する考慮事項

GitLab Runnerを運用する上で、セキュリティは非常に重要な側面です。Runnerはジョブのスクリプトを実行するため、不適切な設定や管理はセキュリティリスクにつながります。

  • Runnerが実行される環境:
    Runnerが動作するマシンは、Gitリポジトリのクローン、ビルド、テスト、そして場合によってはデプロイなど、様々な操作を行います。信頼できるマシン上でRunnerを動作させ、OSのセキュリティパッチを常に適用してください。
  • 権限の管理:
    Runnerサービスは、通常、特定のユーザーアカウントで実行されます。そのユーザーに必要以上の権限を与えないように注意してください。特にShell Executorの場合、Runnerが実行されるユーザーの権限がそのままジョブに引き継がれます。
  • Credential管理 (CI/CD変数):
    デプロイ先のパスワードやAPIキーなどの機密情報は、.gitlab-ci.ymlに直接書き込むべきではありません。GitLabのCI/CD変数として安全に保存し、ジョブ実行時にRunnerに渡されるようにします。変数をマスクしたり、保護されたブランチでのみ利用可能にしたりする設定を活用してください。
  • Shared Runner vs Specific Runner のセキュリティ:
    Shared RunnerやGroup Runnerは複数のプロジェクトで共有されるため、悪意のあるプロジェクトのジョブが他のプロジェクトのリソースやデータにアクセスするリスクがゼロではありません（特にShell Executorの場合）。Executorがジョブごとに環境を分離する（例: Docker, Kubernetes）としても、ホストOSや共有リソースへのアクセスには注意が必要です。機密性の高いジョブや、信頼できないコードを実行する可能性がある場合は、そのプロジェクト専用のSpecific Runnerを使用することを検討してください。
  • 特権モード (Privileged) の利用:
    Docker Executorで privileged: true を設定すると、コンテナがホストOSのカーネルにほぼ無制限にアクセスできるようになります。Dockerイメージのビルドなど、特定のユースケースで必要な場合がありますが、悪用されるとホストOS全体に危険が及ぶ可能性があるため、極力使用を避け、必要な場合でも信頼できるジョブに対してのみ許可するように設定を限定してください。

これらのセキュリティ上の考慮事項を理解し、Runnerのセットアップと運用に反映させることが重要です。

11. まとめ

この記事では、初心者向けにGitLab Runnerの詳細な解説を行いました。

  • GitLab Runnerは、GitLab CI/CDパイプラインで定義されたジョブを実際に実行するエージェントであること。
  • RunnerにはShared, Group, Specificのタイプがあり、用途に合わせて選択できること。
  • RunnerはShell, Docker, Kubernetesなど様々なExecutorを使用してジョブを実行できること。特にDocker Executorが推奨される理由。
  • Linux, Windows, macOS, Dockerなど、様々な環境へのインストール方法。
  • GitLabインスタンスへのRunnerの登録手順と、Registration Tokenの取得方法。
  • config.toml ファイルによるRunnerの詳細設定方法と重要なパラメータ。
  • Runnerの起動・停止、バージョンアップ、監視、そしてトラブルシューティングの基本。
  • .gitlab-ci.yml ファイルで tags を使ってRunnerを指定し、ジョブを実行させる方法。
  • Executorごとの.gitlab-ci.ymlの記述の違い。
  • Cache, Artifacts, Service Containersといった高度な活用方法。
  • Runner運用におけるセキュリティ上の重要な考慮事項。

GitLab Runnerは、GitLab CI/CDを機能させるためのまさに「動力源」です。これを理解し、適切にセットアップ・運用することで、あなたの開発プロセスに自動化と効率化をもたらすCI/CDパイプラインを構築できるようになります。

まずはこの記事で学んだことを参考に、あなたのプロジェクトにSpecific Runnerを1つセットアップし、簡単なテストジョブやビルドジョブを実行してみてください。実際に動かしてみることで、理解がさらに深まるはずです。

CI/CDは一度設定すれば終わりではなく、継続的に改善していくものです。GitLab Runnerと.gitlab-ci.ymlを使いこなし、より効率的で信頼性の高い開発ワークフローを目指しましょう。

コメントする

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

上部へスクロール