コンテナ内でGitLab Runnerを実行する

DockerコンテナでGitLab Runnerを実行して、CI/CDジョブを実行できます。GitLab Runner Dockerイメージには、以下の実行に必要なすべての依存関係が含まれています:

• GitLab Runnerを実行する。
• コンテナ内でCI/CDジョブを実行する。

GitLab Runner Dockerイメージは、UbuntuまたはAlpine Linuxをベースとして使用しています。ホストにGitLab Runnerを直接インストールする場合と同様に、標準のgitlab-runnerコマンドをラップします。

gitlab-runnerコマンドはDockerコンテナで実行されます。このセットアップでは、Dockerデーモンに対する完全な制御が各GitLab Runnerコンテナに委譲されます。このため、他のペイロードも実行するDockerデーモン内部でGitLab Runnerを実行すると、分離の保証が損なわれます。

このセットアップでは、以下に示すように、実行するどのGitLab Runnerコマンドにも、それに相当するdocker runのコマンドがあります:

• Runnerコマンド: gitlab-runner <runner command and options...>
• Dockerコマンド: docker run <chosen docker options...> gitlab/gitlab-runner <runner command and options...>

たとえば、GitLab Runnerのトップレベルのヘルプ情報を取得するには、コマンドのgitlab-runnerの部分をdocker run [docker options] gitlab/gitlab-runnerに置き換えます。次に例を示します:

docker run --rm -t -i gitlab/gitlab-runner --help

NAME:
   gitlab-runner - a GitLab Runner

USAGE:
   gitlab-runner [global options] command [command options] [arguments...]

VERSION:
   17.9.1 (bbf75488)

(...)

Docker Engineのバージョンの互換性

Docker EngineとGitLab Runnerコンテナイメージのバージョンが一致している必要はありません。GitLab Runnerイメージには下位互換性と上位互換性があります。最新の機能とセキュリティ更新を確実に入手するには、常に最新の安定版Docker Engineバージョンを使用する必要があります。

Dockerイメージをインストールしてコンテナを起動する

前提要件:

• Dockerをインストールしていること。
• FAQを読んで、GitLab Runnerの一般的な問題を理解していること。

1. docker pull gitlab/gitlab-runner:<version-tag>コマンドを使用して、gitlab-runner Dockerイメージをダウンロードします。

   利用可能なバージョンタグのリストについては、GitLab Runnerのタグを参照してください。

2. docker run -d [options] <image-uri> <runner-command>コマンドを使用して、gitlab-runner Dockerイメージを実行します。

3. Dockerコンテナでgitlab-runnerを実行する場合は、コンテナの再起動時に設定が失われないようにしてください。永続ボリュームをマウントして設定を保存します。ボリュームは次のいずれかにマウントできます:

   • ローカルシステムボリューム
   • Dockerボリューム

4. （オプション）session_serverを使用している場合は、docker runコマンドに-p 8093:8093を追加して、ポート8093を公開します。

5. （オプション）オートスケールにDocker Machine Executorを使用するには、docker runコマンドにボリュームマウントを追加して、Docker Machineストレージパス（/root/.docker/machine）をマウントします:

   • システムボリュームマウントの場合は、-v /srv/gitlab-runner/docker-machine-config:/root/.docker/machineを追加
   • Dockerの名前付きボリュームの場合は、-v docker-machine-config:/root/.docker/machineを追加

6. 新しいRunnerを登録します。ジョブを取得するには、GitLab Runnerコンテナを登録する必要があります。

利用可能な設定オプションには次のものがあります:

• コンテナのタイムゾーンを設定するには、フラグ--env TZ=<TIMEZONE>を使用します。利用可能なタイムゾーンの一覧を参照してください。
• FIPS準拠のGitLab Runnerイメージを使用する場合は、redhat/ubi9-microベースのgitlab/gitlab-runner:ubi-fipsタグを使用します。
• 信頼できるSSLサーバー証明書をインストールします。

ローカルシステムボリュームを使用する場合

gitlab-runnerコンテナにマウントされた設定ボリュームやその他のリソースとしてローカルシステムを使用するには、次のようにします:

1. （オプション）MacOSシステムでは、デフォルトの場合、/srvは存在しません。セットアップ用に/private/srvを作成するか、または別のプライベートディレクトリを作成します。

2. 次のコマンドを実行します（必要に応じて修正）:

   docker run -d --name gitlab-runner --restart always \
     -v /srv/gitlab-runner/config:/etc/gitlab-runner \
     -v /var/run/docker.sock:/var/run/docker.sock \
     gitlab/gitlab-runner:latest

Dockerボリュームを使用する場合

設定コンテナを使用してカスタムデータボリュームをマウントするには、次の手順に従います:

1. Dockerボリュームを作成します:

   docker volume create gitlab-runner-config

2. 作成したボリュームを使用してGitLab Runnerコンテナを起動します:

   docker run -d --name gitlab-runner --restart always \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v gitlab-runner-config:/etc/gitlab-runner \
     gitlab/gitlab-runner:latest

Runnerの設定を更新する

config.tomlでRunnerの設定を変更したら、docker stopとdocker runでコンテナを再起動して、変更を適用します。

Runnerのバージョンをアップグレードする

前提要件:

• 最初に使用した方法（-v /srv/gitlab-runner/config:/etc/gitlab-runnerまたは-v gitlab-runner-config:/etc/gitlab-runner）でデータボリュームをマウントする必要があります。

1. 最新バージョン（または特定のタグ）をプルします:

   docker pull gitlab/gitlab-runner:latest

2. 既存のコンテナを停止して削除します:

   docker stop gitlab-runner && docker rm gitlab-runner

3. 最初に使用した方法でコンテナを起動します:

   docker run -d --name gitlab-runner --restart always \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v /srv/gitlab-runner/config:/etc/gitlab-runner \
     gitlab/gitlab-runner:latest

Runnerのログを表示する

ログファイルの場所は、Runnerの起動方法によって異なります。次のようになります:

• フォアグラウンドタスクとして（ローカルにインストールされたバイナリとして、またはDockerコンテナ内で）起動する場合は、ログはstdoutに出力されます。
• systemdなどを使用してシステムサービスとして起動する場合は、Syslogなどのシステムログ生成メカニズムでログが使用可能になります。
• Dockerベースのサービスとして起動する場合は、docker logsコマンドを使用します。これは、gitlab-runner ...コマンドがコンテナのメインプロセスであるためです。

たとえば、次のコマンドでコンテナを起動すると、その名前はgitlab-runnerに設定されます:

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

ログを表示するには、gitlab-runnerをコンテナ名に置き換えて次のコマンドを実行します:

docker logs gitlab-runner

コンテナログの処理の詳細については、Dockerドキュメントのdocker container logsを参照してください。

信頼できるSSLサーバー証明書をインストールする

GitLab CI/CDサーバーが自己署名SSL証明書を使用している場合は、RunnerコンテナがGitLab CIサーバー証明書を信頼していることを確認してください。これにより、通信障害の発生を防止できます。

前提要件:

• ca.crtファイルには、GitLab Runnerに信頼させたいすべてのサーバーのルート証明書が含まれている必要があります。

1. （オプション）gitlab/gitlab-runnerイメージは、/etc/gitlab-runner/certs/ca.crtで信頼できるSSL証明書を探します。この動作を変更するには、-e "CA_CERTIFICATES_PATH=/DIR/CERT"設定オプションを使用します。
2. ca.crtファイルをデータボリューム（またはコンテナ）のcertsディレクトリにコピーします。
3. （オプション）コンテナがすでに実行されている場合は、再起動して起動時にca.crtファイルをインポートします。

Dockerイメージ

GitLab Runner 17.10.0では、AlpineベースのDockerイメージはAlpine 3.19を使用します。次のマルチプラットフォームDockerイメージが利用可能です:

• gitlab/gitlab-runner:latest - Ubuntuベース、約800 MB
• gitlab/gitlab-runner:alpine - Alpineベース、約460 MB

UbuntuイメージとAlpineイメージの両方で利用可能なビルド手順については、GitLab Runnerのソースを参照してください。

Runner Dockerイメージを作成する

GitLabリポジトリで更新が利用可能になる前に、イメージのオペレーティングシステムをアップグレードできます。

前提要件:

• IBM Zイメージを使用していないこと（docker-machine依存関係が含まれていないため）。このイメージは、Linux s390xまたはLinux ppc64leプラットフォーム向けにはメンテナンスされていません。現状については、イシュー26551を参照してください。

最新のAlpineバージョン用のgitlab-runner Dockerイメージをビルドするには、次の手順に従います:

1. alpine-upgrade/Dockerfileを作成します。

   ARG GITLAB_RUNNER_IMAGE_TYPE
   ARG GITLAB_RUNNER_IMAGE_TAG
   FROM gitlab/${GITLAB_RUNNER_IMAGE_TYPE}:${GITLAB_RUNNER_IMAGE_TAG}
   
   RUN apk update
   RUN apk upgrade

2. アップグレードされたgitlab-runnerイメージを作成します。

   GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner \
   GITLAB_RUNNER_IMAGE_TAG=alpine-v17.9.1 \
   docker build -t $GITLAB_RUNNER_IMAGE_TYPE:$GITLAB_RUNNER_IMAGE_TAG \
     --build-arg GITLAB_RUNNER_IMAGE_TYPE=$GITLAB_RUNNER_IMAGE_TYPE \
     --build-arg GITLAB_RUNNER_IMAGE_TAG=$GITLAB_RUNNER_IMAGE_TAG \
     -f alpine-upgrade/Dockerfile alpine-upgrade

3. アップグレードされたgitlab-runner-helperイメージを作成します。

   GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner-helper \
   GITLAB_RUNNER_IMAGE_TAG=x86_64-v17.9.1 \
   docker build -t $GITLAB_RUNNER_IMAGE_TYPE:$GITLAB_RUNNER_IMAGE_TAG \
     --build-arg GITLAB_RUNNER_IMAGE_TYPE=$GITLAB_RUNNER_IMAGE_TYPE \
     --build-arg GITLAB_RUNNER_IMAGE_TAG=$GITLAB_RUNNER_IMAGE_TAG \
     -f alpine-upgrade/Dockerfile alpine-upgrade

コンテナでSELinuxを使用する

CentOS、Red Hat、Fedoraなどの一部のディストリビューションでは、基盤となるシステムのセキュリティを強化するために、デフォルトでSELinux（Security-Enhanced Linux）が使用されています。

この設定には注意が必要です。

前提要件:

• Docker executorを使用してコンテナでビルドを実行するには、Runnerが/var/run/docker.sockにアクセスできる必要があります。
• 強制モードでSELinuxを使用する場合は、Runnerが/var/run/docker.sockにアクセスするときにPermission deniedエラーが発生しないようにするため、selinux-dockersockをインストールします。

1. ホストに永続ディレクトリを作成します（mkdir -p /srv/gitlab-runner/config）。

2. ボリュームで:Zを使用してDockerを実行します:

   docker run -d --name gitlab-runner --restart always \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \
     gitlab/gitlab-runner:latest