チュートリアル: Runnerの作成と登録を自動化する

このチュートリアルでは、Runnerの作成と登録を自動化する方法について説明します。

Runnerの作成と登録を自動化するには:

このチュートリアルの手順では、Runner認証トークンを使用したRunnerの作成と登録について説明します。これは、非推奨となった登録トークンによる登録方法に代わるものです。詳細については、新しいRunner登録ワークフローを参照してください。

はじめる前

GitLab RunnerがGitLabインスタンスにインストールされている必要があります。
インスタンスRunnerを作成するには、管理者である必要があります。
グループRunnerを作成するには、管理者であるか、グループのオーナーロールを持っている必要があります。
プロジェクトRunnerを作成するには、管理者であるか、プロジェクトのメンテナーロールを持っている必要があります。

アクセストークンを作成する

REST APIを使用してRunnerを作成できるように、アクセストークンを作成します。

次のアクセストークンを作成できます:

共有Runner、グループRunner、プロジェクトRunnerで使用するパーソナルアクセストークン。
グループRunnerおよびプロジェクトRunnerで使用するグループアクセストークンまたはプロジェクトアクセストークン。

アクセストークンは、GitLab UIで1回のみ表示されます。ページを離れると、トークンにアクセスできなくなります。HashiCorp VaultやKeeper Secrets Manager Terraformプラグインなどのシークレット管理ソリューションを使用して、トークンを保存することをおすすめします。

パーソナルアクセストークンを作成する

拡張された最大許容ライフタイム制限の可用性は、機能フラグによって制御されます。詳細については、履歴を参照してください。

左側のサイドバーで、自分のアバターを選択します。
プロファイルの編集を選択します。
左側のサイドバーで、パーソナルアクセストークンを選択します。
新しいトークンを追加を選択します。
トークンの名前と有効期限を入力します。
- トークンは、その日付の午前0時（UTC）に有効期限切れになります。有効期限が2024-01-01のトークンは、2024-01-01の00:00:00 UTCに期限切れになります。
- 有効期限を入力しない場合、有効期限は現在の日付より365日後に自動的に設定されます。
- デフォルトでは、この日付は現在の日付より最大365日後に設定できます。GitLab 17.6以降では、この制限を400日に延長できます。
スコープを選択セクションで、create_runner（create_runner）チェックボックスをオンにします。
Create personal access token（パーソナルアクセストークンを作成）を選択します。

プロジェクトアクセストークンまたはグループアクセストークンを作成する

拡張された最大許容ライフタイム制限の可用性は、機能フラグによって制御されます。詳細については、履歴を参照してください。

プロジェクトアクセストークンは内部ユーザーとして扱われます。内部ユーザーがプロジェクトアクセストークンを作成した場合、そのトークンは、表示レベルが内部に設定されているすべてのプロジェクトにアクセスできます。

プロジェクトアクセストークンを作成するには:

左側のサイドバーで、検索または移動先を選択して、プロジェクトまたはグループを見つけます。
設定 > アクセストークンを選択します。
新しいトークンを追加を選択します
名前を入力します。トークン名は、グループまたはプロジェクトを表示する権限を持つすべてのユーザーに表示されます。
トークンの有効期限を入力します。
- トークンは、その日付の午前0時（UTC）に有効期限切れになります。有効期限が2024-01-01のトークンは、2024-01-01の00:00:00 UTCに期限切れになります。
- 有効期限を入力しない場合、有効期限は現在の日付より365日後に自動的に設定されます。
- デフォルトでは、この日付は現在の日付より最大365日後に設定できます。GitLab 17.6以降では、この制限を400日に延長できます。
- インスタンス全体の最大ライフタイム設定により、GitLab Self-Managedインスタンスで許可される最大ライフタイムが制限される場合があります。
ロールを選択ドロップダウンリストで、次の手順を実行します:
- プロジェクトアクセストークンの場合は、メンテナーを選択します。
- グループアクセストークンの場合は、オーナーを選択します。
スコープを選択セクションで、create_runner（create_runner）チェックボックスをオンにします。
Create project access token（プロジェクトアクセストークンを作成）を選択します。

Runner設定を作成する

Runner設定では、要件に合わせてRunnerを設定します。

Runner設定を作成すると、Runnerを登録するためのRunner認証が付与されます。1つまたは複数のRunnerを同じRunner認証トークンで登録すると、これらのRunnerを同じ設定にリンクできます。Runner設定は、config.tomlファイルに保存されます。

次のいずれかを使用して、Runner設定を作成できます:

GitLab REST API。
gitlab_user_runner Terraformリソース。

GitLab REST APIを使用する場合

はじめる前に、次のものが必要です:

GitLabインスタンスのURL。たとえば、プロジェクトがgitlab.example.com/yourname/yourprojectでホスティングされている場合、GitLabインスタンスのURLはhttps://gitlab.example.comです。
グループRunnerまたはプロジェクトRunnerの場合は、グループまたはプロジェクトのID番号。ID番号は、プロジェクトまたはグループの概要ページで、プロジェクト名またはグループ名の下に表示されます。

POST /user/runners RESTエンドポイントでアクセストークンを使用してRunnerを作成します:

curlを使用し、エンドポイントを呼び出してRunnerを作成します:

curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
  --data "runner_type=project_type"
  --data "project_id=<project_id>"
  --data "description=<your_runner_description>"
  --data "tag_list=<your_comma_separated_job_tags>"
  --header "PRIVATE-TOKEN: <project_access_token>"

curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
  --data "runner_type=group_type"
  --data "group_id=<group_id>"
  --data "description=<your_runner_description>"
  --data "tag_list=<your_comma_separated_job_tags>"
  --header "PRIVATE-TOKEN: <group_access_token>"

curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
  --data "runner_type=instance_type"
  --data "description=<your_runner_description>"
  --data "tag_list=<your_comma_separated_job_tags>"
  --header "PRIVATE-TOKEN: <personal_access_token>"

返されたtoken値を安全な場所またはシークレット管理ソリューションに保存します。token値は、API応答で1回のみ返されます。

`gitlab_user_runner` Terraformリソースを使用する場合

TerraformでRunner設定を作成するには、GitLab Terraformプロバイダーのgitlab_user_runner Terraformリソースを使用します。

設定ブロックの例を次に示します:

resource "gitlab_user_runner" "example_runner" {
  runner_type = "instance_type"
  description = "my-runner"
  tag_list = ["shell", "docker"]
}

Runnerのインストールと登録を自動化する

パブリッククラウドの仮想マシンインスタンスでRunnerをホストする場合は、Runnerのインストールと登録を自動化できます。

Runnerとその設定を作成した後、同じRunner認証トークンを使用して、同じ設定で複数のRunnerを登録できます。たとえば、同じexecutorタイプとジョブタグを持つ複数のインスタンスRunnerをターゲットコンピューティングホストにデプロイできます。同じRunner認証トークンで登録された各Runnerには一意のsystem_idがあります。このIDはGitLab Runnerによってランダムに生成され、ローカルファイルシステムに保存されます。

Runnerを登録し、Google Compute Engineにデプロイするために使用できる自動化GitLabワークフローの例を次に示します:

Terraform Infrastructure as Codeを使用して、Google Cloud Platform（GCP）でホストされている仮想マシンにRunnerアプリケーションをインストールします。
GCP Terraformプロバイダーで、metadataキーを使用して、GCP仮想マシンのRunner設定ファイルにRunner認証トークンを追加します。

ターゲットGitLabインスタンスにRunnerを登録するには、GCP Terraformプロバイダーから入力されたcloud-initスクリプトを使用します。次に例を示します:

#!/bin/bash
apt update
curl --location "https://packages.gitlab.com/install/repositories/runner/
gitlab-runner/script.deb.sh" | bash
GL_NAME=$(curl 169.254.169.254/computeMetadata/v1/instance/name
--header "Metadata-Flavor:Google")
GL_EXECUTOR=$(curl 169.254.169.254/computeMetadata/v1/instance/attributes/
gl_executor --header "Metadata-Flavor:Google")
apt update
apt install -y gitlab-runner
gitlab-runner register --non-interactive --name="$GL_NAME" --url="https://gitlab.com"
  --token="$RUNNER_TOKEN" --request-concurrency="12" --executor="$GL_EXECUTOR"
  --docker-image="alpine:latest"
systemctl restart gitlab-runner

同じ設定のRunnerを表示する

Runnerの作成と登録を自動化したので、GitLab UIで同じ設定を使用するRunnerを表示できます。

左側のサイドバーの下部で、管理者を選択します。
CI/CD > Runnersを選択します。
検索ボックスに、Runnerの説明を入力するか、Runnerのリストを検索します。
同じ設定を使用するRunnerを表示するには、詳細タブのRunnersの横にある詳細を表示を選択します。