CI/CDパイプラインを成功に導く陰の立役者、それが GitLab Runner です。.gitlab-ci.yml ファイルに定義されたジョブを実行し、テストの起動、アプリケーションのビルド、コードのデプロイを担います。
Runnerがなければ、パイプラインは設計図のままです。Runnerがあれば、それは具体的な動作として再現できるものになります。本記事では、GitLab Runnerとは何か、インストール・設定の方法、そして最大限に活用するためのベストプラクティスをご紹介します。
GitLab Runnerとは？
GitLab RunnerはオープンソースのGoで書かれたアプリケーションで、CI/CDパイプラインのジョブを実行します。デベロッパーがコードをプッシュすると、GitLabがパイプラインをトリガーし、利用可能なRunnerにジョブを振り分けます。RunnerはジョブをRunnerし、その結果（ログ、アーティファクト、ステータス）をGitLabに返します。
パイプラインとは、ジョブ（コンパイル、テスト、デプロイ）を自動化した一連の流れのことです。Runnerは、特定のマシン上でそれらを実行するエージェントです。RunnerのExecutorは、ジョブが実行される環境（Docker、Shell、Kubernetesなど）を定義します。
GitLab CI/CDで利用できるRunnerの種類
GitLab Runnerでは、アクセスを許可する対象に応じて、次のRunnerスコープを利用できます。
- インスタンスRunner：GitLabインスタンス上のすべてのグループとプロジェクトで利用可能。
- グループRunner：グループ内のすべてのプロジェクトおよびサブグループで利用可能。
- プロジェクトRunner：特定のプロジェクトに紐付けられています。通常、プロジェクトRunnerは一度に1つのプロジェクトのみで使用されます。
これらのRunnerは、2つの方法でホストできます。
- ホスト型Runner：GitLabが管理し、GitLab.com上で利用可能。インストール不要で、素早く開始できますが、設定の自由度は制限されます。
- セルフホスト型Runner：独自のサーバー、仮想マシン、またはクラスター上にインストール・設定・管理します。完全なコントロールが可能で、特定の環境にも柔軟に対応できます。
GitLab Runnerがサポートするエグゼキューター
GitLab Runnerのインストール時には、Executor（ジョブが実行される環境）を選択する必要があります。Executorの選択は、パイプラインのセキュリティ、パフォーマンス、柔軟性に直接影響します。
主なExecutorは以下のとおりです。
- Docker：各ジョブを隔離されたコンテナ内で実行します。高速かつ柔軟で、ほとんどのプロジェクトに推奨されます。
- Shell：ホストマシン上でジョブを直接実行します。シンプルですが、分離性はありません。
- Kubernetes：Kubernetesのポッド内でジョブを実行し、ネイティブなスケーラビリティを備えています。
- VirtualBox / Parallels：macOSなど特定の環境でジョブを実行します。
選択はニーズによって異なりますが、ほとんどのプロジェクトではDockerが最適です。Executorの詳細については、ドキュメントをご覧ください。
GitLab Runnerのインストール方法
GitLab Runnerのインストール方法は、使用するOSとターゲット環境によって異なります。以下に代表的なシナリオをご紹介します。
Linuxへのインストール（Debian/Ubuntu）
Linuxは、特にサーバー側でセルフホスト型Runnerをホストする最も一般的な環境です。インストール方法は次の3通りです。
- GitLabの公式リポジトリ経由
.debまたは.rpmパッケージ経由- バイナリファイル経由
以下の例は、Debian/UbuntuにおいてGitLabリポジトリからパッケージをインストールする手順を示しています。
- GitLabの公式リポジトリを追加します。
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
- GitLab Runnerの最新バージョンをインストールします。特定バージョンをインストールする場合は次のステップに進んでください。
sudo apt install gitlab-runner
- 特定バージョンのGitLab Runnerをインストールする場合：
apt-cache madison gitlab-runner
sudo apt install gitlab-runner=17.7.1-1 gitlab-runner-helper-images=17.7.1-1
gitlab-runnerの特定バージョンをgitlab-runner-helper-imagesの同バージョンなしにインストールしようとすると、次のようなエラーが発生する場合があります。
sudo apt install gitlab-runner=17.7.1-1
...
The following packages have unmet dependencies:
gitlab-runner : Depends: gitlab-runner-helper-images (= 17.7.1-1) but 17.8.3-1 is to be installed
E: Unable to correct problems, you have held broken packages.
- Runnerを登録します。
sudo gitlab-runner register
WindowsおよびmacOSへのインストール
プロジェクトにビルド固有の要件がある場合は、次の手順に従ってWindowsまたはmacOSにGitLab Runnerをインストールすることもできます。
DockerによるRunnerのインストール
DockerはGitLab Runnerをセットアップする最もシンプルかつ迅速な方法の一つです。複雑なインストール作業なしにDockerコンテナ内でRunnerを実行でき、隔離された再現性の高い環境を活用できます。
迅速なテストや一時的な開発環境、またはすでにコンテナを多用しているチームに最適な方法です。
- コンテナを起動します。
docker run -d --name gitlab-runner --restart always \
-v /srv/gitlab-runner/config:/etc/gitlab-runner \
-v /var/run/docker.sock:/var/run/docker.sock \
gitlab/gitlab-runner:latest
- Runnerを登録します。
docker exec -it gitlab-runner gitlab-runner register
KubernetesによるRunnerのインストール
KubernetesへのGitLab RunnerのインストールはGitLabのHelm Chartを使用します。これはKubernetesクラスター内にGitLab Runnerインスタンスをデプロイする公式の方法です。
GitLabのHelm ChartからGitLab Runnerをインストールする手順は以下のとおりです。
- GitLab Helmリポジトリを追加します。
helm repo add gitlab https://charts.gitlab.io
- アクセス可能なGitLab Runnerのバージョンを確認します。
helm search repo -l gitlab/gitlab-runner
- GitLab Runnerの最新バージョンにアクセスできない場合は、次のコマンドでチャートを更新してください。
helm repo update gitlab
values.yamlファイルでGitLab Runnerを設定した後、必要に応じてパラメーターを変更しながら次のコマンドを実行します。
# For Helm 3
helm install --namespace <NAMESPACE> gitlab-runner \
-f <CONFIG_VALUES_FILE> \
gitlab/gitlab-runner
<NAMESPACE>：GitLab RunnerをインストールするKubernetesの名前空間。<CONFIG_VALUES_FILE>：カスタム設定が含まれるvaluesファイルへのパス。作成方法はドキュメントをご参照ください。- 特定バージョンのGitLab Runner Helm Chartをインストールする場合は、
helm installコマンドに--version <RUNNER_HELM_CHART_VERSION>を追加してください。任意バージョンのHelm Chartをインストールできますが、新しいvalues.ymlファイルは古いバージョンと互換性がない場合があります。
KubernetesでGitLab Runnerをインストールする詳細については、ドキュメントをご覧ください。
GitLab Runnerのインストールについてのよくあるご質問は、FAQをご参照ください。
GitLab Runnerの登録方法
インストール後、GitLab Runnerを登録することで、GitLabインスタンスからジョブを取得できるようになります。この手順では、インストール済みのRunnerを1つ以上のGitLabインスタンスに接続します。
GitLab Runnerの登録方法はいくつかあります。本記事では、認証トークンを使用したRunner登録に焦点を当てます。
前提条件
- Runner認証トークンを取得してください。次のいずれかの方法で取得できます。
- インスタンス、グループ、またはプロジェクトのRunnerを作成する。手順についてはRunnerの管理に関するドキュメントをご参照ください。
config.tomlファイル内のRunner認証トークンを確認する。Runner認証トークンのプレフィックスはglrt-です。
Runnerが登録されると、設定内容はconfig.tomlファイルに保存されます。このファイルはGitLab Runnerのメイン設定ファイルで、RunnerとCI/CDジョブの実行に必要なすべての設定を含んでいます。このファイルはいつでも編集でき、変更内容はサービスの再起動なしに次のジョブから反映されます。
Runner認証トークンを使用してRunnerを登録するには、次の手順を実施します。
- インストール方法に応じた登録コマンドを実行し、
- GitLabインスタンスのURL（GitLab.comまたはGitLab Self-Managed）を入力し、
- Runner認証トークンを入力し、
- RunnerとジョブタグのDescriptionを追加し、
- 選択したExecutor（Docker、Shell、Kubernetesなど）を入力します。
同一のホストマシン上で異なる設定を持つ複数のRunnerを登録するには、registerコマンドを繰り返します。また、同一の設定を複数のホストマシンに登録するには、各Runner登録で同じRunner認証トークンを使用してください。
非インタラクティブモードを使用して、追加の引数でRunnerを登録することもできます。
Linuxを例に挙げると：
sudo gitlab-runner register \
--non-interactive \
--url "https://gitlab.com/" \
--token "$RUNNER_TOKEN" \
--executor "docker" \
--docker-image alpine:latest \
--description "docker-runner"
Runnerの動作確認と使用開始
ワークフローにRunnerを組み込む前に、正常に動作しているかどうかを確認してください。
- GitLab UIで確認する。
a. プロジェクト内で 設定 > CI/CD > Runners に移動します。
b. Runnerがアクティブかつ正常であることを確認します。
- 選択したインストール方法に応じてコマンドラインで確認します。
.gitlab-ci.ymlファイルを作成してシンプルなパイプラインでテストします。
test-runner:
stage: test
script:
- echo "Hello GitLab Runner"
- hostname
- date
tags:
- my-tags # ⚠️ Replace with YOUR runner's tags
GitLab Runnerのセキュリティと最適化のベストプラクティス
設定が不適切なGitLab Runnerは、パフォーマンスの低下やセキュリティ上の問題を引き起こす可能性があります。CI/CDパイプラインを最大限に活用するためのベストプラクティスをご紹介します。
Runnerのセキュリティ
- 隔離された環境を優先する：ホストマシン上でコマンドを直接実行するShellモードではなく、ジョブ間の明確な分離を提供するDockerまたはKubernetesのExecutorを優先して使用してください。
- 権限を制限する：必要でない限り、RunnerにAdminの権限を付与しないでください。攻撃対象領域を減らすため、最小限の権限で設定してください。
- タグによるアクセスを制御する：特定のジョブのみが実行されるよう、Runnerに特定のタグを割り当ててください。これにより、意図しないジョブが機密性の高いRunner上で実行されるリスクを防げます。
パイプラインのパフォーマンスと速度
- 軽量イメージを使用する：Docker ExecutorではビルドやCI要件に最適化されたイメージを選択してください（例：十分であれば
ubuntuではなくalpine）。これによりコンテナの起動時間を短縮できます。 - キャッシュを設定する：GitLabのキャッシュ機能を活用して、複数のパイプライン間で依存関係や生成ファイルを再利用してください。これにより全体的な実行時間が短縮されます。
- 並列実行する：ジョブを並列で実行できる複数のステージに分割し、パイプライン全体の時間を短縮してください。
メンテナンスと信頼性
- Runnerを定期的に更新する：各バージョンにはバグ修正と新機能が含まれています。RunnerをGitLabのバージョンと同期させておくことで、互換性と安定性が確保されます。
- Runnerを監視する：組み込みメトリクス（例：Prometheus経由）を使用して、負荷、ジョブ実行時間、リソース使用状況を追跡してください。これによりボトルネックを事前に把握できます。
- 冗長性を確保する：重要な環境では、負荷を分散しインシデントによるパイプライン停止を防ぐため、複数のRunnerをインストールしてください。
GitLab CI/CDをさらに活用するために
GitLab Runnerは、GitLabのCI/CDパイプライン、セキュリティテスト、完全な自動化と連携することで真の価値を発揮します。共有サービスモデルにおけるGitLab Runnerフリートの管理に関するベストプラクティスについては、ドキュメントもあわせてご覧ください。
