要件
Docker
Linux
macOS
Windows
FreeBSD
一行登録コマンド
- UIで作成したRunnerを認証トークンで登録します。
- 登録トークンによるランナーの登録（非推奨）
  - レガシー互換の登録処理
Check registration token エラー
[[runners]] 設定テンプレートファイル
- 物件例

ランナーの登録

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

Runnerの登録は、1つ以上のGitLabインスタンスとRunnerをリンクするプロセスです。

register コマンドを繰り返すことで、同じホストマシンに複数の Runner を登録し、それぞれを異なる設定にすることができます。

要件

ランナーを登録する前に、まず必要なことがあります：

GitLabがインストールされているサーバーとは別のサーバーにGitLab Runner をインストールします。
ランナーの作成

GitLab.comでRunnerを登録する場合、gitlab-ci coordinator URL はhttps://gitlab.com。

Docker

前提条件：

GitLab Runnerをコンテナにインストールします。

以下の手順では、インストール中に作成したコンテナを登録するためにgitlab-runner コンテナを起動します。登録が終わると、作成した設定が設定ボリューム（例えば/srv/gitlab-runner/config ）に書き込まれ、その設定ボリュームを使って Runner が読み込みます。

Dockerコンテナを使用してRunnerを登録するには：

マウントタイプに基づいてregisterコマンドを実行します：
ローカルシステムのボリュームマウントの場合：
```
docker run --rm -it -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register
```
/srv/gitlab-runner/config インストール時に/srv/gitlab-runner/config 以外の設定ボリュームを使用した場合は、正しいボリュームでコマンドを更新してください。
Dockerボリュームマウントの場合：
```
docker run --rm -it -v gitlab-runner-config:/etc/gitlab-runner gitlab/gitlab-runner:latest register
```
GitLabインスタンスのURL（gitlab-ci coordinator URL ）を入力してください。
Runner を登録するために取得したトークンを入力します。
ランナーの説明を入力します。この値は後で GitLab ユーザーインターフェースで変更することができます。
ランナーに関連するタグをカンマ区切りで入力します。この値は後でGitLabユーザーインターフェイスで変更できます。
ランナーのメンテナンスノートを任意で入力します。
ランナーの Executor を指定します。ほとんどの使用例では、docker を入力します。
Executor にdocker を入力した場合、.gitlab-ci.yml で定義していないプロジェクトで使用するデフォルトイメージを聞かれます。

Linux

LinuxでRunnerを登録するには：

以下のコマンドを実行します：
```
sudo gitlab-runner register
```
プロキシの後ろにいる場合は、環境変数を追加してから登録コマンドを実行してください：
```
export HTTP_PROXY=http://yourproxyurl:3128
export HTTPS_PROXY=http://yourproxyurl:3128
   
sudo -E gitlab-runner register
```
GitLabインスタンスのURL（gitlab-ci coordinator URL ）を入力してください。
Runner を登録するために取得したトークンを入力します。
ランナーの説明を入力します。この値は後で GitLab ユーザーインターフェースで変更することができます。
ランナーに関連するタグをカンマ区切りで入力します。この値は後でGitLabユーザーインターフェイスで変更できます。
ランナーのメンテナンスノートを任意で入力します。
ランナーの Executor を指定します。ほとんどの使用例では、docker を入力します。
Executor にdocker を入力した場合、.gitlab-ci.yml で定義していないプロジェクトで使用するデフォルトイメージを聞かれます。

macOS

MacOSでRunnerを登録する前にDocker.appをインストールしてください。

MacOSでRunnerを登録するには：

以下のコマンドを実行します：
```
gitlab-runner register
```
GitLabインスタンスのURL（gitlab-ci coordinator URL ）を入力してください。
Runner を登録するために取得したトークンを入力します。
ランナーの説明を入力します。この値は後で GitLab ユーザーインターフェースで変更することができます。
ランナーに関連するタグをカンマ区切りで入力します。この値は後でGitLabユーザーインターフェイスで変更できます。
ランナーのメンテナンスノートを任意で入力します。
ランナーの Executor を指定します。ほとんどの使用例では、docker を入力します。
Executor にdocker を入力した場合、.gitlab-ci.yml で定義されていないプロジェクトで使用するデフォルトイメージを尋ねられます。

Windows

WindowsでRunnerを登録するには：

以下のコマンドを実行します：
```
.\gitlab-runner.exe register
```
GitLabインスタンスのURL（gitlab-ci coordinator URL ）を入力してください。
Runner を登録するために取得したトークンを入力します。
ランナーの説明を入力します。この値は後で GitLab ユーザーインターフェースで変更することができます。
ランナーに関連するタグをカンマ区切りで入力します。この値は後でGitLabユーザーインターフェイスで変更できます。
ランナーのメンテナンスノートを任意で入力します。
ランナーの Executor を指定します。ほとんどの使用例では、docker を入力します。
Executor にdocker を入力した場合、.gitlab-ci.yml で定義していないプロジェクトで使用するデフォルトイメージを聞かれます。

FreeBSD

FreeBSD で Runner を登録するには：

以下のコマンドを実行します：

sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register

GitLabインスタンスのURL（gitlab-ci coordinator URL ）を入力してください。
Runner を登録するために取得したトークンを入力します。
ランナーの説明を入力します。この値は後で GitLab ユーザーインターフェースで変更することができます。
ランナーに関連するタグをカンマ区切りで入力します。この値は後でGitLabユーザーインターフェイスで変更できます。
ランナーのメンテナンスノートを任意で入力します。
ランナーの Executor を指定します。ほとんどの使用例では、docker を入力します。
Executor にdocker を入力した場合、.gitlab-ci.yml で定義していないプロジェクトで使用するデフォルトイメージを聞かれます。

一行登録コマンド

非インタラクティブモードを使用してRunnerを登録する場合、register サブコマンドを使用するか、同等の環境変数を使用することができます。

すべてのregister サブコマンドのリストを表示するには、次のコマンドを実行します：

gitlab-runner register -h

UIで作成したRunnerを認証トークンで登録します。

GitLab Runner 15.10 で導入されました。

最も一般的なオプションを使って Runner を登録するには、次のようにします：

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

DockerコンテナでRunnerを実行している場合は、次の例のような構成でregister ：

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

登録トークンによるランナーの登録（非推奨）

GitLab 15.6 で非推奨。

この機能はGitLab 15.6で非推奨となり、17.0で削除される予定です。この変更はブレークチェンジです。GitLab 16.2以降では、レガシー互換の登録処理において、いくつかの非推奨パラメータが登録時に渡された場合、自動的に無視されます。詳しくは、レガシー互換登録処理をご覧ください。

最も一般的なオプションを使って Runner を登録するには、次の例のような構成でregister コマンドを実行してください：

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"

Dockerコンテナでランナーを実行する場合、register コマンドは以下のような構造になっています：

docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --executor "docker" \
  --docker-image alpine:latest \
  --url "https://gitlab.com/" \
  --registration-token "PROJECT_REGISTRATION_TOKEN" \
  --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 パラメーターは GitLab Runner 12.0 で追加されました。これは、GitLab 11.11で導入された登録APIパラメータを使用します。保護されたランナーを作成するには、登録時にこのパラメーターを使用します。保護されたランナーには、--access-level="ref_protected" パラメータを使用します。保護されていないランナーには、代わりに--access-level="not_protected" を使用するか、値を未定義のままにしてください。この値はプロジェクトの[設定]>[CI/CD]メニューでオン/オフを切り替えることができます。

--maintenance-note パラメーターは GitLab Runner 14.8 で追加されました。ランナーのメンテナンスに関する情報を追加するために使用できます。最大文字数は255文字です。

レガシー互換の登録処理

登録トークンといくつかのRunner設定引数はGitLab 15.6で非推奨となり、GitLab 17.0で削除される予定です。

自動化ワークフローの中断を最小限にするため、legacy-compatible registration process はレガシーパラメータ--registration-tokenに認証トークンが指定された場合にトリガーします。この処理により、以下のコマンドラインパラメータは無視されます。これらのパラメータは、UI または API で Runner を作成する場合にのみ設定できます。

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

`Check registration token` エラー

check registration token のエラーメッセージは、入力された登録トークンをGitLabインスタンスが認識できない場合に表示されます。このイシューは、インスタンスグループやプロジェクトの登録トークンがGitLabで変更された場合や、ユーザーが登録トークンを正しく入力しなかった場合に発生する可能性があります。

このエラーが発生した場合、まずGitLab管理者に登録トークンが有効であることを確認してもらう必要があります。

さらに、プロジェクトやグループへのRunner登録がGitLab管理者によって許可されていることを確認してください。

`[[runners]]` 設定テンプレートファイル

GitLab Runner 12.2で導入されました。

環境変数やコマンドラインオプションで設定できないRunner設定もあります。

使用例：

環境変数はスライスをサポートしていません。
コマンドラインオプションのサポートは、Kubernetes Executorボリュームツリー全体の設定には意図的に利用できません。

これは、GitLab Runner公式のHelmチャートのような、何らかの自動化によって処理される環境にとっては問題です。このような場合、唯一の解決策はRunnerが登録された後に手動でconfig.toml ファイルを更新することでした。これは理想的ではなく、エラーが起こりやすく、信頼性もありません。特に、同じGitLab Runnerインストールに対して複数の登録が行われた場合です。

この問題は、_設定テンプレート_ファイルを使うことで解決できます。

設定テンプレートファイルを使うには、register にファイルへのパスを渡してください：

--template-config コマンドラインオプションを指定します。
TEMPLATE_CONFIG_FILE 環境変数。

設定テンプレートファイルがサポートします：

[[runners]] セクションのみ。
グローバルオプションはありません。

--template-config またはTEMPLATE_CONFIG_FILE を使用した場合、[[runners]] エントリーの [[runners]]設定は、通常のconfig.toml ファイルで[[runners]] 新しく作成された [[runners]]エント[[runners]] リーの設定にマージさ [[runners]]れます。

マージは、_空の_オプションに対してのみ行われます。つまり

空の文字列。
ヌルまたは存在しないエントリ。
ゼロ。

これで

register コマンド呼び出し中にコマンドラインオプションおよび/または環境変数で提供されたすべての設定が優先されます。
テンプレートはギャップを埋め、追加の設定を追加します。

物件例

Kubernetes-executorベースのRunnerをテストプロジェクトに登録し、config.toml ：

$ sudo gitlab-runner register \
     --config /tmp/test-config.toml \
     --non-interactive \
     --url "https://gitlab.com" \
     --registration-token __REDACTED__ \
     --name test-runner \
     --tag-list kubernetes,test \
     --locked \
     --paused \
     --executor kubernetes \
     --kubernetes-host http://localhost:9876/

Runtime platform                                    arch=amd64 os=linux pid=1684 revision=436955cb version=15.11.0

Registering runner... succeeded                     runner=__REDACTED__
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

上記のコマンドは、以下のconfig.toml ファイルを作成します：

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "test-runner"
  url = "https://gitlab.com"
  token = "__REDACTED__"
  executor = "kubernetes"
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
  [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]

提供されたコマンドラインオプションから作成された基本設定を見ることができます：

Runnerの認証情報（URLとトークン）。
指定されたエクゼキューター。
デフォルトの空のセクションrunners.kubernetes 登録時に提供された一つのオプションだけが記入されています。

通常、Kubernetes Executorを使えるようにするにはもう少しオプションを設定する必要がありますが、今回の例では上記で十分です。

ここで、Kubernetes Executor用にemptyDir ボリュームを設定する必要があるとします。環境変数でもコマンドラインオプションでも、登録中にこれを追加する方法はありません。手動でファイルの末尾にこのように追加する必要があります：

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

TOMLは適切なインデントを必要としないので（エントリの順序に依存しています）、必要な変更をファイルの最後に追加するだけです。しかし、1つのconfig.toml ファイル内に、より多くの[[runners]] セクションが登録される場合、これは厄介なことになります。新しいものが常に末尾にあるという仮定は危険です。

GitLab Runner 12.2では、--template-config フラグを使うことで、これがとても簡単になりました。

$ cat > /tmp/test-config.template.toml << EOF
[[runners]]
  [runners.kubernetes]
    [runners.kubernetes.volumes]
      [[runners.kubernetes.volumes.empty_dir]]
        name = "empty_dir"
        mount_path = "/path/to/empty_dir"
        medium = "Memory"
EOF

このファイルを手に入れたら、今度は--template-config /tmp/test-config.template.toml オプションを追加して Runner の登録をやり直します。この変更を除けば、残りの登録コマンドはまったく同じです：

$ sudo gitlab-runner register \
     --config /tmp/test-config.toml \
     --template-config /tmp/test-config.template.toml \
     --non-interactive \
     --url "https://gitlab.com" \
     --registration-token __REDACTED__ \
     --name test-runner \
     --tag-list kubernetes,test \
     --locked \
     --paused \
     --executor kubernetes \
     --kubernetes-host http://localhost:9876/

Runtime platform                                    arch=amd64 os=linux pid=8798 revision=436955cb version=15.11.0

Registering runner... succeeded                     runner=__REDACTED__
Merging configuration from template file
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

見てわかるように、登録コマンドの出力に少し変化があります。Merging configuration from template file 。

では、テンプレートを使用した後の設定ファイルがどのように見えるか見てみましょう：

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "test-runner"
  url = "https://gitlab.com"
  token = "__REDACTED__"
  executor = "kubernetes"
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
  [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"

設定は以前とほとんど同じであることがわかります。唯一の変更は、[[runners.kubernetes.volumes.empty_dir]] のエントリーとそのオプションがファイルの最後にあることです。これは登録によって作成された[[runners]] エントリーに追加されたものです。また、ファイル全体が同じメカニズムで保存されるので、適切なインデントもあります。

設定テンプレートに設定が含まれていて、同じ設定がregister コマンドに register渡される場合register 、 registerコマンドregister に渡されたものが register設定テンプレート内で指定されたものよりも優先されます。

$ cat > /tmp/test-config.template.toml << EOF
[[runners]]
  executor = "docker"
EOF

$ sudo gitlab-runner register \
     --config /tmp/test-config.toml \
     --template-config /tmp/test-config.template.toml \
     --non-interactive \
     --url "https://gitlab.com" \
     --registration-token __REDACTED__ \
     --name test-runner \
     --tag-list shell,test \
     --locked \
     --paused \
     --executor shell

Runtime platform                                    arch=amd64 os=linux pid=12359 revision=436955cb version=15.11.0

Registering runner... succeeded                     runner=__REDACTED__
Merging configuration from template file
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

見てわかるように、登録コマンドはshell 、テンプレートはdocker 。最終的な設定内容を見てみましょう：

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "test-runner"
  url = "https://gitlab.com"
  token = "__REDACTED__"
  executor = "shell"
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]

register コマンドオプションで設定された設定が優先され、最終的な設定に選ばれました。

ランナーの登録

要件

Docker

Linux

macOS

Windows

FreeBSD

一行登録コマンド

UIで作成したRunnerを認証トークンで登録します。

登録トークンによるランナーの登録（非推奨）

レガシー互換の登録処理

`Check registration token` エラー

`[[runners]]` 設定テンプレートファイル

物件例

Help & feedback

Docs

Product

Feature availability and product trials

Get Help

ランナーの登録

要件

Docker

Linux

macOS

Windows

FreeBSD

一行登録コマンド

UIで作成したRunnerを認証トークンで登録します。

登録トークンによるランナーの登録（非推奨）

レガシー互換の登録処理

Check registration token エラー

[[runners]] 設定テンプレートファイル

物件例

Help & feedback

Docs

Product

Feature availability and product trials

Get Help

`Check registration token` エラー

`[[runners]]` 設定テンプレートファイル