Runnerの登録

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

Runnerの登録とは、Runnerを1つ以上のGitLabインスタンスに関連付けるプロセスです。GitLabインスタンスからジョブを取得するには、Runnerを登録する必要があります。

要件

Runnerを登録する前に:

GitLab Runnerを、GitLabがインストールされているサーバーとは別のサーバーにインストールします。
DockerでRunnerを登録するために、DockerコンテナにGitLab Runnerをインストールします。

Runner認証トークンで登録する

前提要件:

Runner認証トークンを取得します。次のいずれかの方法があります:
- インスタンス、グループ、またはプロジェクトのRunnerを作成します。手順については、manageランナーを参照してください。
- config.tomlファイルの中でRunner認証トークンを見つける。Runner認証トークンのプレフィックスはglrt-です。

Runnerを登録すると、config.tomlに設定が保存されます。

Runner認証トークンを使用してRunnerを登録するには:

registerコマンドを実行します:
sudo gitlab-runner register
プロキシの背後にいる場合は、環境変数を追加してから、登録コマンドを実行します:
export HTTP_PROXY=http://yourproxyurl:3128 export HTTPS_PROXY=http://yourproxyurl:3128 sudo -E gitlab-runner register
gitlab-runner register
.\gitlab-runner.exe register
sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
コンテナを使用して登録するには、次のいずれかを実行します:
- 適切な設定ボリュームマウントによる有効期間の短いgitlab-runnerコンテナを使用します:
  ローカルシステムボリュームマウントの場合:
  docker run --rm -it -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register
  インストール中に/srv/gitlab-runner/config以外の設定ボリュームを使用した場合は、適切なボリュームでコマンドを更新します。
  Dockerボリュームマウントの場合:
  docker run --rm -it -v gitlab-runner-config:/etc/gitlab-runner gitlab/gitlab-runner:latest register
- アクティブなRunnerコンテナ内で実行可能ファイルを使用します:
  docker exec -it gitlab-runner gitlab-runner register
GitLabのURLを入力します:
- GitLab Self-ManagedのRunnerの場合は、GitLabインスタンスのURLを使用します。たとえば、プロジェクトがgitlab.example.com/yourname/yourprojectでホストされている場合、GitLabインスタンスのURLはhttps://gitlab.example.comです。
- GitLab.comのRunnerの場合、GitLabインスタンスのURLはhttps://gitlab.comです。
Runner認証トークンを入力します。
Runnerの説明を入力します。
ジョブタグをカンマで区切って入力します。
（オプション）Runnerのメンテナンスノートを入力します。
executorのタイプを入力します。

異なる設定の複数のRunnerを同じホストマシンに登録するには、それぞれについてregisterコマンドを繰り返します。
複数のホストマシンに同じ設定を登録するには、各Runnerの登録に同じRunner認証トークンを使用します。詳細については、Runner設定の再利用を参照してください。

非対話モードを使用して、追加の引数を使用してRunnerを登録することもできます:

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

.\gitlab-runner.exe register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker-windows" \
  --docker-image mcr.microsoft.com/windows/servercore:1809_amd64 \
  --description "docker-runner"

sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

Runner登録トークンで登録する（非推奨）

Runnerの登録トークンといくつかのRunnerの設定引数は非推奨になりました。これらは、GitLab 20.0での削除が予定されています。代わりにRunner認証トークンを使用してください。詳細については、新しいRunner登録ワークフローに移行するを参照してください。

前提要件:

管理者エリアでRunner登録トークンが有効になっている必要があります。
登録したいインスタンス、グループ、またはプロジェクトでRunner登録トークンを取得します。手順については、manageランナーを参照してください。

Runnerを登録すると、config.tomlに設定が保存されます。

Runner登録トークンを使用してRunnerを登録するには:

registerコマンドを実行します:
sudo gitlab-runner register
プロキシの背後にいる場合は、環境変数を追加してから、登録コマンドを実行します:
export HTTP_PROXY=http://yourproxyurl:3128 export HTTPS_PROXY=http://yourproxyurl:3128 sudo -E gitlab-runner register
gitlab-runner register
.\gitlab-runner.exe register
sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
インストール中に作成したコンテナを登録するため、有効期間の短いgitlab-runnerコンテナを起動するには:
- ローカルシステムボリュームマウントの場合:
  docker run --rm -it -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register
  インストール中に/srv/gitlab-runner/config以外の設定ボリュームを使用した場合は、適切なボリュームでコマンドを更新します。
- Dockerボリュームマウントの場合:
  docker run --rm -it -v gitlab-runner-config:/etc/gitlab-runner gitlab/gitlab-runner:latest register
GitLabのURLを入力します:
- GitLab Self-ManagedのRunnerの場合は、GitLabインスタンスのURLを使用します。たとえば、プロジェクトがgitlab.example.com/yourname/yourprojectでホストされている場合、GitLabインスタンスのURLはhttps://gitlab.example.comです。
- GitLab.comの場合、GitLabインスタンスのURLはhttps://gitlab.comです。
Runnerを登録するために取得したトークンを入力します。
Runnerの説明を入力します。
ジョブタグをカンマで区切って入力します。
（オプション）Runnerのメンテナンスノートを入力します。
executorのタイプを入力します。

異なる設定の複数のRunnerを同じホストマシンに登録するには、それぞれについてregisterコマンドを繰り返します。

非対話モードを使用して、追加の引数を使用してRunnerを登録することもできます:

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "Free-form maintainer notes about this runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "Free-form maintainer notes about this runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

.\gitlab-runner.exe register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker-windows" \
  --docker-image mcr.microsoft.com/windows/servercore:1809_amd64 \
  --description "docker-runner" \
  --maintenance-note "Free-form maintainer notes about this runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "Free-form maintainer notes about this runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "Free-form maintainer notes about this runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

--access-levelは、保護されたRunnerを作成するかどうかを設定します。
- 保護されたRunnerの場合は、--access-level="ref_protected"パラメータを使用します。
- 保護されていないRunnerの場合は、--access-level="not_protected"を使用するか、値を未定義のままにします。
--maintenance-noteを使用すると、Runnerのメンテナンスに役立つ情報を追加できます。最大長は255文字です。

レガシー互換登録プロセス

Runnerの登録トークンといくつかのRunnerの設定引数は非推奨になりました。これらは、GitLab 20.0での削除が予定されています。自動化ワークフローへの影響を最小限にするため、レガシーパラメータ--registration-tokenの中でRunner認証トークンが指定されている場合、legacy-compatible registration processがトリガーされます。

レガシー互換登録プロセスでは、次のコマンドラインパラメータは無視されます。これらのパラメータは、UIまたはAPIでRunnerが作成された場合にのみ設定可能です。

--locked
--access-level
--run-untagged
--maximum-timeout
--paused
--tag-list
--maintenance-note

設定テンプレートを使用して登録する

設定テンプレートを使用すると、registerコマンドでサポートされていない設定でRunnerを登録できます。

前提要件:

テンプレートファイルの格納場所となるボリュームは、GitLab Runnerコンテナにマウントされている必要があります。
Runner認証トークンまたは登録トークン:
- Runner認証トークンを取得します（推奨）。次のいずれかの方法があります:
  - 登録したいインスタンス、グループ、またはプロジェクトでRunner認証トークンを取得します。手順については、manageランナーを参照してください。
  - config.tomlファイルの中でRunner認証トークンを見つける。Runner認証トークンのプレフィックスはglrt-です。
- （非推奨）インスタンス、グループ、またはプロジェクトの各RunnerのためのRunner登録トークンを取得する。手順については、manageランナーを参照してください。

設定テンプレートは、次の理由によりregisterコマンドの一部の引数をサポートしていない自動化環境で使用できます:

環境に基づく環境変数のサイズ制限。
Kubernetes用のexecutorボリュームで使用できないコマンドラインオプション。

設定テンプレートでサポートされるのは単一の[[runners]]セクションだけであり、グローバルオプションはサポートされません。

Runnerを登録するには、次のようにします:

.toml形式の設定テンプレートファイルを作成し、仕様を追加します。次に例を示します:

[[runners]]
  [runners.kubernetes]
  [runners.kubernetes.volumes]
    [[runners.kubernetes.volumes.empty_dir]]
      name = "empty_dir"
      mount_path = "/path/to/empty_dir"
      medium = "Memory"

ファイルのパスを追加します。次のいずれかを使用できます:

コマンドラインの非対話モード:

$ sudo gitlab-runner register \
    --template-config /tmp/test-config.template.toml \
    --non-interactive \
    --url "https://gitlab.com" \
    --token <TOKEN> \ "# --registration-token if using the deprecated runner registration token"
    --name test-runner \
    --executor kubernetes
    --host = "http://localhost:9876/"

.gitlab.yamlファイルの中の環境変数:
```
variables:
  TEMPLATE_CONFIG_FILE = <file_path>
```
環境変数を更新する場合、registerコマンドでファイルパスを毎回追加する必要はありません。

Runnerを登録すると、config.toml内で作成された[[runners]]エントリと設定テンプレートの設定がマージされます:

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "test-runner"
  url = "https://gitlab.com"
  token = "glrt-<TOKEN>"
  executor = "kubernetes"
  [runners.kubernetes]
    host = "http://localhost:9876/"
    bearer_token_overwrite_allowed = false
    image = ""
    namespace = ""
    namespace_overwrite_allowed = ""
    privileged = false
    service_account_overwrite_allowed = ""
    pod_labels_overwrite_allowed = ""
    pod_annotations_overwrite_allowed = ""
    [runners.kubernetes.volumes]

      [[runners.kubernetes.volumes.empty_dir]]
        name = "empty_dir"
        mount_path = "/path/to/empty_dir"
        medium = "Memory"

テンプレートの設定がマージされるのは、次の場合のみです:

空の文字列
nullまたは存在しないエントリ
ゼロ値

コマンドライン引数と環境変数は、設定テンプレートの設定よりも優先されます。たとえば、テンプレートではdockerexecutorを指定し、コマンドラインではshellを指定した場合、設定されるexecutorはshellになります。

GitLab Community Editionインテグレーションテスト用にRunnerを登録する

GitLab Community Editionインテグレーションをテストするには、設定テンプレートを使用して、制限付きDocker executorでRunnerを登録します。

プロジェクトRunnerを作成します。

[[runners.docker.services]]セクションを含むテンプレートを作成します:

$ cat > /tmp/test-config.template.toml << EOF
[[runners]]
[runners.docker]
[[runners.docker.services]]
name = "mysql:latest"
[[runners.docker.services]]
name = "redis:latest"

EOF

Runnerを登録します:

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --template-config /tmp/test-config.template.toml \
  --description "gitlab-ce-ruby-3.1" \
  --executor "docker" \
  --docker-image ruby:3.1

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --template-config /tmp/test-config.template.toml \
  --description "gitlab-ce-ruby-3.1" \
  --executor "docker" \
  --docker-image ruby:3.1

.\gitlab-runner.exe register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --template-config /tmp/test-config.template.toml \
  --description "gitlab-ce-ruby-3.1" \
  --executor "docker" \
  --docker-image ruby:3.1

sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --template-config /tmp/test-config.template.toml \
  --description "gitlab-ce-ruby-3.1" \
  --executor "docker" \
  --docker-image ruby:3.1

docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --template-config /tmp/test-config.template.toml \
  --description "gitlab-ce-ruby-3.1" \
  --executor "docker" \
  --docker-image ruby:3.1

その他の設定オプションについては、高度な設定を参照してください。

DockerによるRunnerの登録

DockerコンテナによるRunner登録後:

設定が設定ボリュームに書き込まれます。たとえば、/srv/gitlab-runner/configなどです。
コンテナが設定ボリュームを使用してRunnerを読み込みます。

gitlab-runner restartがDockerコンテナ内で実行される場合、GitLab Runnerは既存のプロセスを再起動せず、新しいプロセスを開始します。設定変更を適用するには、Dockerコンテナを再起動します。

トラブルシューティング

エラー: `Check registration token`

check registration token（登録トークンを確認してください）エラーメッセージは、登録中に入力したRunner登録トークンをGitLabインスタンスが認識しない場合に表示されます。この問題は、次のいずれかの場合に発生する可能性があります:

GitLabで、インスタンス、グループ、またはプロジェクトのRunner登録トークンが変更された。
正しくないRunner登録トークンが入力された。

このエラーが発生した場合は、GitLab管理者に次のことを依頼できます:

Runner登録トークンが有効であることを確認する。
プロジェクトまたはグループでRunner登録が許可されていることを確認する。

エラー: `410 Gone - runner registration disallowed`

410 Gone - runner registration disallowed（Runner登録が無効です）エラーメッセージは、登録トークンによるRunner登録が無効になっている場合に表示されます。

このエラーが発生した場合は、GitLab管理者に次のことを依頼できます:

Runner登録トークンが有効であることを確認する。
インスタンスでのRunner登録が許可されていることを確認する。
グループまたはプロジェクトのRunner登録トークンの場合、それぞれ対応するグループやプロジェクトでのRunner登録が許可されていることを確認する。

Runnerの登録

要件

Runner認証トークンで登録する

Runner登録トークンで登録する（非推奨）

レガシー互換登録プロセス

設定テンプレートを使用して登録する

GitLab Community Editionインテグレーションテスト用にRunnerを登録する

DockerによるRunnerの登録

トラブルシューティング

エラー: Check registration token

エラー: 410 Gone - runner registration disallowed

エラー: `Check registration token`

エラー: `410 Gone - runner registration disallowed`