• 要件
• GNU/Linux
• macOS
• Windows
• FreeBSD
• Docker
• 一行登録コマンド
• [[runners]] 設定テンプレートファイル
  • 例

ランナー登録

Runnerの登録は、RunnerとGitLabインスタンスをバインドするプロセスです。

要件

Runnerを登録する前に、まず必要なことがあります：

• GitLabがインストールされているサーバーとは別のサーバーにインストールします。
• GitLabのインターフェイスから共有または特定のRunnerのトークンを取得します。

GNU/Linux

GNU/LinuxでRunnerを登録するには：

1. 以下のコマンドを実行してください：

   sudo gitlab-runner register
   

2. GitLabインスタンスのURLを入力します：

   Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
   https://gitlab.com
   

3. Runnerを登録するために取得したトークンを入力してください：

   Please enter the gitlab-ci token for this runner
   xxx
   

4. Runnerの説明を入力します。後でGitLabのUIで変更することができます：

   Please enter the gitlab-ci description for this runner
   [hostname] my-runner
   

5. Runnerに関連するタグを入力します。後でGitLabのUIで変更することができます：

   Please enter the gitlab-ci tags for this runner (comma separated):
   my-tag,another-tag
   

6. Runnerエクゼキューターの登場です：

   Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:
   docker
   

7. Dockerをexecutorに選んだ場合、.gitlab-ci.ymlで定義していないプロジェクトで使うデフォルトのイメージを聞かれます：

   Please enter the Docker image (eg. ruby:2.6):
   alpine:latest
   

macOS

MacOSでRunnerを登録するには：

1. 以下のコマンドを実行してください：

   gitlab-runner register
   

2. GitLabインスタンスのURLを入力します：

   Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
   https://gitlab.com
   

3. Runnerを登録するために取得したトークンを入力してください：

   Please enter the gitlab-ci token for this runner
   xxx
   

4. Runnerの説明を入力します。後でGitLabのUIで変更することができます：

   Please enter the gitlab-ci description for this runner
   [hostname] my-runner
   

5. Runnerに関連するタグを入力します。後でGitLabのUIで変更することができます：

   Please enter the gitlab-ci tags for this runner (comma separated):
   my-tag,another-tag
   

6. Runnerエクゼキューターの登場です：

   Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:
   docker
   

7. Dockerをexecutorに選んだ場合、.gitlab-ci.ymlで定義していないプロジェクトで使うデフォルトのイメージを聞かれます：

   Please enter the Docker image (eg. ruby:2.6):
   alpine:latest
   

   注意 Docker.appがmacにインストールされていることを確認してください。

Windows

WindowsでRunnerを登録するには：

1. 以下のコマンドを実行してください：

   ./gitlab-runner.exe register
   

2. GitLabインスタンスのURLを入力します：

   Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
   https://gitlab.com
   

3. Runnerを登録するために取得したトークンを入力してください：

   Please enter the gitlab-ci token for this runner
   xxx
   

4. Runnerの説明を入力します。後でGitLabのUIで変更することができます：

   Please enter the gitlab-ci description for this runner
   [hostname] my-runner
   

5. Runnerに関連するタグを入力します。後でGitLabのUIで変更することができます：

   Please enter the gitlab-ci tags for this runner (comma separated):
   my-tag,another-tag
   

6. Runnerエクゼキューターの登場です：

   Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:
   docker
   

7. Dockerをexecutorに選んだ場合、.gitlab-ci.ymlで定義していないプロジェクトで使うデフォルトのイメージを聞かれます：

   Please enter the Docker image (eg. ruby:2.6):
   alpine:latest
   

同じマシンに異なる設定で複数のRunnerを登録したい場合は、./gitlab-runner.exe register コマンドを繰り返してください。

FreeBSD

FreeBSD で Runner を登録するには：

1. 以下のコマンドを実行してください：

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

2. GitLabインスタンスのURLを入力します：

   Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
   https://gitlab.com
   

3. Runnerを登録するために取得したトークンを入力してください：

   Please enter the gitlab-ci token for this runner
   xxx
   

4. Runnerの説明を入力します。後でGitLabのUIで変更することができます：

   Please enter the gitlab-ci description for this runner
   [hostname] my-runner
   

5. Runnerに関連するタグを入力します。後でGitLabのUIで変更することができます：

   Please enter the gitlab-ci tags for this runner (comma separated):
   my-tag,another-tag
   

6. Runnerエクゼキューターの登場です：

   Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:
   docker
   

7. Dockerをexecutorに選んだ場合、.gitlab-ci.ymlで定義していないプロジェクトで使うデフォルトのイメージを聞かれます：

   Please enter the Docker image (eg. ruby:2.6):
   alpine:latest
   

Docker

これらの手順は、GitLab Runnerをコンテナで実行した後に実行するものです。このセクションでは、インストール中に作成したコンテナを登録するために、エフェメラルgitlab-runner コンテナを起動します。登録が完了すると、結果の設定が選択した設定ボリューム（例：/srv/gitlab-runner/config）に書き込まれ、その設定ボリュームを使用してRunnerによって自動的にロードされます。

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

1. registerコマンドを実行してください：

   ローカルシステムのボリュームマウントの場合：

   docker run --rm -it -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register
   

   注: インストール時に** 以外の設定ボリュームを使用した場合は、正しいボリュームでコマンドを更新してください。

   Dockerボリュームマウントの場合：

   docker run --rm -it -v gitlab-runner-config:/etc/gitlab-runner gitlab/gitlab-runner:latest register
   

2. GitLabインスタンスのURLを入力します：

   Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
   https://gitlab.com
   

3. Runnerを登録するために取得したトークンを入力してください：

   Please enter the gitlab-ci token for this runner
   xxx
   

4. Runnerの説明を入力します。後でGitLabのUIで変更することができます：

   Please enter the gitlab-ci description for this runner
   [hostname] my-runner
   

5. Runnerに関連するタグを入力します。後でGitLabのUIで変更することができます：

   Please enter the gitlab-ci tags for this runner (comma separated):
   my-tag,another-tag
   

6. Runnerエクゼキューターの登場です：

   Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:
   docker
   

7. Dockerをexecutorに選んだ場合、.gitlab-ci.ymlで定義していないプロジェクトで使うデフォルトのイメージを聞かれます：

   Please enter the Docker image (eg. ruby:2.6):
   alpine:latest
   

一行登録コマンド

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

すべてのregister サブコマンドのリストを見るには、次のようにします：

gitlab-runner register -h

最も一般的なオプションを使って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" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

Runnerを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" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

--access-level パラメーターは GitLab Runner 12.0 で追加されました。これは GitLab 11.11 で導入された登録 API パラメーターを使用します。保護された Runnerを作成するには、登録時にこのパラメーターを使用します。保護された Runner の場合は、--access-level="ref_protected" パラメーターを使用します。保護されていない Runner の場合は、代わりに--access-level="not_protected" を使用するか、値を未定義のままにします。この値は後でプロジェクトの設定 > CI/CDメニューでオンまたはオフに切り替えることができます。

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

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

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

使用例：

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

これは、GitLab Runner公式のHelmチャートのような、何らかの自動化によって処理される環境にとっては問題です。 このような場合、唯一の解決策は、Runnerが登録された後に手動でconfig.toml ファイルを更新することでした。これは理想的ではなく、エラーが発生しやすく、信頼性がありません。 特に、同じ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=88310882 version=11.10.0~beta.1251.g88310882

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_annotations_overwrite_allowed = ""
    [runners.kubernetes.volumes]

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

• Runner の認証情報（URL とトークン）。
• 執行者が指定しました。
• デフォルトの空のセクションrunners.kubernetes 、登録時に提供された1つのオプションのみが記入されています。

通常、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

このファイルを手に入れたので、Runnerを再度登録しようとしますが、今度は--template-config /tmp/test-config.template.toml オプションを追加します。この変更以外は、登録コマンドの残りの部分は全く同じです：

$ 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=88310882 version=11.10.0~beta.1251.g88310882

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_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=88310882 version=11.10.0~beta.1251.g88310882

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 コマンドオプションで設定されたコンフィギュレーションが優先され、最終的なコンフィギュレーションに選ばれました。