1. CI/CDサーバーの悪夢:ビルド環境が「ゴミ屋敷」と化すとき
1つのまな板を10人のシェフが共有して調理しているキッチンを想像してみてください。生の魚をさばいた直後に、まな板を洗いもせずそのまま果物を切り始める人がいる……その結果がどうなるかは容易に想像がつくでしょう。複数の開発者が1台の共有サーバーにコードをプッシュしてビルドやテストを実行する現場も、まさにこれと同じ混乱に陥りがちです。
かつては、用意したVPSにShell Runnerを導入し、サーバー上で直接ビルドコマンドを実行する手法がよく使われていました。しかし、ここから問題が始まります。リポジトリAはNode 16を要求し、リポジトリBはNode 20を必須とし、リポジトリCはPython 3.9を必要とする――ほんの数週間で、サーバー上には競合するランタイムの各バージョンが乱立することになります。パイプラインが赤くエラーを表示するたびに、エンジニアは慌ててサーバーへSSHログインし、肥大化したゴミファイルを削除したり、ライブラリの依存関係の衝突を解消したりする羽目になります。この不毛な状況を根本から断ち切るために必要なのが、使い捨てでクリーンな環境を実現するDocker Executorです。
2. GitLab RunnerとDocker Executorの仕組み
この構成は、以下のコンポーネントが連携してスムーズに動作します。
- GitLab Server: プッシュされたコードを受け取り、
.gitlab-ci.ymlを読み取ってRunnerへジョブを割り当てます。 - GitLab Runner: バックグラウンドで常駐(デーモン)し、指示を受け取って各ジョブの実行プロセスを制御します。
- Docker Executor: 隔離されたコンテナ内でジョブを実行する仕組みです。ホストOSに直接パッケージをインストールする代わりに、Runnerが指定されたイメージに基づいて完全に新規のコンテナを起動します。パッケージの取得、コンパイル、テスト実行などの全操作はそのコンテナ内部で完結します。ジョブが完了するとコンテナは即座に破棄されるため、ホストサーバーは常にクリーンな状態に保たれます。
- キャッシュメモリ(Cache): クリーンなコンテナの唯一のデメリットは、起動直後は中身が空っぽであるという点です。毎回ギガバイト単位の依存ライブラリをダウンロードしていては、パイプラインの遅さにストレスが溜まるばかりです。キャッシュはこの課題を的確に解決します。
node_modules/やvendor/のような容量の大きいディレクトリを外部ディスクに保持しておき、ジョブ実行時にコンテナへマウントして再利用します。
3. 最適化されたステップ別セットアップ手順
ステップ 1: Docker ComposeによるGitLab Runnerの起動
現在のDocker Compose v2構文(docker compose)を使用すれば、コンテナを非常にスマートに管理できます。まずVPS上に作業ディレクトリを用意します。
mkdir -p /opt/gitlab-runner && cd /opt/gitlab-runner
nano docker-compose.yml
ファイルに以下の設定を貼り付けます。
services:
gitlab-runner:
image: gitlab/gitlab-runner:latest
container_name: gitlab-runner
restart: always
volumes:
- /opt/gitlab-runner/config:/etc/gitlab-runner
- /var/run/docker.sock:/var/run/docker.sock
バックグラウンドでコンテナを起動します。
docker compose up -d
ステップ 2: GitLabインスタンスへのRunner登録
GitLabの管理画面でSettings > CI/CD > Runnersにアクセスし、Runner Authentication Token(通常はプレフィックスがglrt-)を取得します。続いて、以下の登録コマンドを実行します。
docker compose exec gitlab-runner gitlab-runner register \n --non-interactive \n --url "https://gitlab.com/" \n --token "glrt-your-runner-token" \n --executor "docker" \n --docker-image "alpine:latest" \n --description "Production Docker Runner"
ステップ 3: config.tomlの最適化によるキャッシュとイメージ取得の高速化
生成された設定ファイル /opt/gitlab-runner/config/config.toml を開きます。
nano /opt/gitlab-runner/config/config.toml
並列数の拡張やローカルキャッシュ機構を有効化するため、主要なパラメータを編集します。
concurrent = 4
check_interval = 0
[session_server]
session_timeout = 1800
[[runners]]
name = "Production Docker Runner"
url = "https://gitlab.com/"
id = 1
token = "glrt-your-runner-token"
executor = "docker"
[runners.custom_build_dir]
[runners.docker]
tls_verify = false
image = "alpine:latest"
privileged = false
disable_entrypoint_overwrite = false
oom_kill_disable = false
disable_cache = false
volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock:ro"]
shm_size = 0
pull_policy = ["if-not-present"]
ここで指定した pull_policy = ["if-not-present"] パラメータは極めて重要です。これにより、Runnerはジョブごとにネットワーク経由でイメージを再取得する時間を省き、ホスト上に存在するローカルイメージを優先して利用するようになります。
ステップ 4: キャッシュをスマートに活用する .gitlab-ci.yml の設計
プロジェクトのルートディレクトリに .gitlab-ci.yml を作成します。
stages:
- test
- build
default:
image: node:20-alpine
variables:
npm_config_cache: "$CI_PROJECT_DIR/.npm"
cache:
key:
files:
- package-lock.json
paths:
- .npm/
- node_modules/
policy: pull-push
unit_test:
stage: test
script:
- npm ci --cache .npm --prefer-offline
- npm run test
build_artifact:
stage: build
script:
- npm run build
artifacts:
paths:
- dist/
expire_in: 1 week
cache:
key:
files:
- package-lock.json
paths:
- .npm/
- node_modules/
policy: pull
build_artifact ステージにおける効果的なテクニックは、policy: pull を指定することです。Runnerはキャッシュのダウンロードのみを行い、ジョブ終了時の不要な再圧縮やアップロードをスキップします。このチューニングにより、パイプライン全体の所要時間を従来の4〜5分からわずか25〜35秒程度にまで短縮可能です。
4. 環境標準化によって得られるメリット
クリーンなビルド環境を整えることは、「ローカル環境では動くのにCIでは落ちる」という典型的なトラブルの根本的な排除を意味します。蓄積されたログファイルによってディスク容量が予期せず圧迫される心配もありません。Docker Executorとローカルキャッシュを組み合わせることで、サーバーの堅牢性を維持しながら、コミットごとの高速なフィードバックループを実現できます。
