GitLab Runner

GitLab RunnerはGitLab CI/CDと連携してパイプラインでジョブを実行するアプリケーションです。

GitLab.com SaaS Runnerをご利用ください。

GitLab.comを使用する場合、GitLabがホストするSaaSランナー上でCI/CDジョブを実行することができます。これらのランナーはGitLabによって管理され、GitLab.comと完全にインテグレーションされています。デフォルトでは、これらのRunnerは全てのプロジェクトで有効になっています。プロジェクトのオーナーロールを持っている場合、Runnerを無効にすることができます。

自己管理ランナーを使う

別の方法として、GitLab Runnerをインストールし、GitLab.comや自分のインスタンスに自分のRunnerを登録することもできます。セルフマネージドランナーを使うには、GitLab Runnerをあなたが所有または管理するインフラストラクチャにインストールします。

Runner のフリートをスケール

あなたの組織がランナー・フリートを持って規模を拡大する場合、ランナーのパフォーマンスをどのようにモニターし、調整するかを計画する必要があります。

GitLab Runner のバージョン

互換性の理由から、GitLab Runnerのメジャー・マイナーバージョンはGitLabのメジャー・マイナーバージョンと同期している必要があります。古いRunnerは新しいGitLabバージョンでも動作しますし、その逆も同様です。しかし、バージョンの違いが存在する場合、機能が利用できなかったり、正しく動作しないことがあります。

マイナーバージョンアップデート間の後方互換性は保証されています。しかし、GitLabのマイナーバージョンアップデートにより、GitLab Runnerが同じマイナーバージョンでなければならない新機能が導入されることがあります。

note
GitLab Runner 15.0は登録APIリクエストフォーマットの変更を導入しました。これにより、GitLab Runnerは14.8より低いバージョンのGitLabと通信できなくなりました。GitLabバージョンに適したRunnerバージョンを使用するか、GitLabアプリケーションをアップグレードする必要があります。

独自のRunnerをホストしているがリポジトリはGitLab.comでホストしている場合、GitLab.comは継続的に更新されるため、GitLab Runnerを最新バージョンに更新してください。

ランナーの登録

アプリケーションをインストールしたら 登録ランナーを登録します。ランナーはGitLabから送られてくるCI/CDジョブを実行するエージェントです。

ランナーを登録すると、GitLabインスタンスとGitLab Runnerがインストールされているマシンとの間の通信を設定することになります。

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

エクゼキューター

Runnerを登録する際には、Executorを選択する必要があります。

実行者 エクゼキュータは各ジョブが実行される環境を決定します。

使用例：

  • CI/CD ジョブに PowerShell コマンドを実行させたい場合、Windows サーバーに GitLab Runner をインストールし、シェル Executor を使うランナーを登録します。
  • CI/CD ジョブにカスタム Docker コンテナでコマンドを実行させたい場合は、Linux サーバーに GitLab Runner をインストールし、Docker Executor を使うランナーを登録します。

これらは可能な設定のほんの一部です。GitLab Runnerを仮想マシンにインストールして、別の仮想マシンをエクゼキューターとして使うこともできます。

GitLab RunnerをDockerコンテナにインストールし、Docker Executorを選択してジョブを実行する場合、”Docker-in-Docker “設定と呼ばれることがあります。

GitLab UIでRunnerにアクセスできる人

Runnerを登録する前に、GitLabの全員がアクセスできるようにするのか、それとも特定のGitLabグループやプロジェクトに限定するのかを決めておく必要があります。

ランナーには、アクセスさせたい人に応じて三種類あります：

ランナーのスコープは登録時に定義されます。これにより、ランナーはどのプロジェクトで利用できるかを知ることができます。

タグ

ランナーを登録する際、以下のタグを追加することができます。 タグを追加できます。

CI/CDジョブが実行されると、割り当てられたタグを見てどのRunnerを使うべきかがわかります。タグはジョブで利用可能なランナーのリストをフィルタリングする唯一の方法です。

たとえば、Runnerがruby タグを持っている場合、プロジェクトの.gitlab-ci.yml ファイルにこのコードを追加します：

job:
  tags:
    - ruby

ジョブが実行されると、ruby タグを持つ Runner が使用されます。

ランナーの設定

ランナーは ランナーの設定config.toml ファイルを編集することで、ランナーを設定できます。こ れ は 、ラ ン ナ ー の イ ン ス ト ー ル プ ロ セ ス 中 に イ ン ス ト ー ル さ れ る フ ァ イ ル で す 。

このファイルでは、特定のランナーまたはすべてのランナーの設定を編集することができます。

ロギングやキャッシュなどの設定を指定できます。同時実行、メモリ、CPUの制限などを設定できます。

ランナーの監視

Prometheus を使用して、次のことができます。 ランナーをすることができます。現在実行中のジョブの数やRunnerが使用しているCPUの量などを見ることができます。

ジョブを実行するためにRunnerを使用します。

ランナーが設定され、プロジェクトで利用できるようになると、CI/CDジョブがランナーを利用できるようになります。

機能

GitLab Runnerには以下の機能があります。

  • 複数のジョブを同時に実行。
  • 複数のサーバーで複数のトークンを使用（プロジェクト単位でも）。
  • トークンごとに同時実行ジョブ数を制限します。
  • ジョブを実行できます：
    • ローカル
    • Dockerコンテナを使って。
    • Dockerコンテナを使用し、SSH経由でジョブを実行します。
    • 異なるクラウドや仮想化ハイパーバイザー上でのオートスケールによるDockerコンテナの使用。
    • リモートSSHサーバーへの接続。
  • Goで書かれ、他の要件なしで単一のバイナリとしてディストリビューションされています。
  • Bash、PowerShell Core、Windows PowerShell をサポートしています。
  • GNU/Linux、MacOS、Windows（Dockerを実行できる場所であればほとんどどこでも）上で動作します。
  • ジョブの実行環境をカスタマイズできます。
  • 再起動なしの自動設定再読み込み。
  • Docker、Docker-SSH、Parallels、SSH実行環境に対応した簡単なセットアップ。
  • Docker コンテナのキャッシュが可能。
  • GNU/Linux、MacOS、Windows用のサービスとして簡単にインストールできます。
  • PrometheusメトリクスHTTPサーバーを内蔵。
  • Prometheusメトリクスやその他のジョブ固有のデータを監視し、GitLabに渡すためのレフェリーワーカー。

ランナーの実行フロー

この図はランナーがどのように登録され、ジョブがどのようにリクエストされ処理されるかを示しています。また、どのアクションが登録、認証、ジョブトークンを使用するかも示しています。

sequenceDiagram participant GitLab participant GitLabRunner participant Executor opt registration GitLabRunner ->>+ GitLab: POST /api/v4/runners with registration_token GitLab -->>- GitLabRunner: Registered with runner_token end loop job requesting and handling GitLabRunner ->>+ GitLab: POST /api/v4/jobs/request with runner_token GitLab -->>+ GitLabRunner: job payload with job_token GitLabRunner ->>+ Executor: Job payload Executor ->>+ GitLab: clone sources with job_token Executor ->>+ GitLab: download artifacts with job_token Executor -->>- GitLabRunner: return job output and status GitLabRunner -->>- GitLab: updating job output and status with job_token end

用語解説

この用語集では、GitLab Runnerに関連する用語の定義を提供します。

  • GitLab Runner：GitLab CIジョブをターゲットコンピューティングプラットフォーム上で実行するためにインストールするアプリケーション。
  • ランナー：ホストプラットフォーム上でコードを実行し、UIに表示するエージェント。ランナーが同じトークンで登録されている場合、ランナーはランナーとランナーマネージャーのコレクションを表すことができます。
  • ランナーマネージャー：オートスケールのために複数のランナーを作成できるランナーの一種。使用されるエクゼキューターのタイプに固有。
  • ランナーワーカー：ジョブを実行するためにランナーによってホストコンピューティングプラットフォーム上に作成されるプロセス。

トラブルシューティング

よくあるイシューのトラブルシューティング方法をご紹介します。

貢献者

貢献することは大歓迎です。詳しくはCONTRIBUTING.md と開発ドキュメントをご覧ください。

GitLab Runnerプロジェクトのレビュアーであれば、Reviewing GitLab Runnerドキュメントをお読みください。

GitLab Runnerプロジェクトのリリースプロセスもレビューしてください。

チェンジログ

最近の変更点については、変更履歴をご覧ください。

ライセンス

このコードはMITライセンスの下でディストリビューションされています。LICENSEファイルをご覧ください。