マージリクエストを出してから、パイプラインが緑になるまで20分。
その間に別の作業へ切り替え、戻ってきたころには元の文脈を忘れている……。
そんな経験はありませんか?
GitLab CI/CDの実行時間が伸びる原因の多くは、ジョブそのものの重さではなく、同じ処理を毎回ゼロからやり直していることにあります。
依存パッケージの再取得やビルド成果物の再生成は、その典型例です。
これを解消する仕組みとして、GitLabには「キャッシュ」と「アーティファクト」が用意されています。
ところが、両者は見た目が似ているため、役割を混同したまま使われがちです。
整理すると、次のような違いがあります。
- キャッシュ:ジョブ間で再利用する依存関係など、あれば速くなる「最適化」のためのデータ
- アーティファクト:後続のステージへ確実に引き渡す、またはダウンロードして残すための「成果物」
この違いを理解せずに運用すると、キャッシュに依存したパイプラインが不安定になったり、アーティファクトが肥大化してストレージを圧迫したりします。
設計の誤りは、実行時間の悪化という形で確実に表れるのです。
本記事では、両者の性質の違いを論理的に整理したうえで、実行時間を短縮するための運用設計を順を追って解説します。
GitLab CI/CDの実行時間が長くなる原因とは?まず計測すべきポイント

パイプラインを速くしたいとき、最初に設定ファイルを書き換えたくなる気持ちは理解できます。
しかし、計測せずに最適化を始めるのは、プロファイラを使わずにコードを高速化しようとするのと同じです。
ボトルネックでない箇所を改善しても、全体の実行時間はほとんど変わりません。
パイプラインの所要時間は、ステージが直列に並ぶ場合、各ステージで最も遅いジョブの時間を合計したものになります。
つまり、短縮すべきはすべてのジョブではなく、クリティカルパス上のジョブです。
さらに、ジョブの実行時間だけでなく、Runnerの空きを待つキュー時間も含まれる点に注意が必要です。
まずは次の3点を切り分けることをおすすめします。
- ジョブ本体の実行時間:ビルドやテストなど、スクリプトが実際に動いている時間
- キュー待ち時間:Runnerに割り当てられるまでの待機時間
- 準備時間:イメージの取得、リポジトリのチェックアウト、キャッシュやアーティファクトの展開にかかる時間
パイプライン実行時間の内訳をジョブ単位で確認する方法
最も手軽なのは、プロジェクトの「CI/CD」から開けるパイプライン画面と、ジョブ詳細のログです。
ジョブログの先頭には、イメージの取得やチェックアウトの様子が出力されます。
スクリプトの実行前にすでに数十秒かかっているなら、原因はスクリプトではなく準備段階にあると判断できます。
複数のパイプラインを横断して傾向を見たい場合は、GitLab APIでジョブごとの実行時間とキュー時間を取得すると効率的です。
curl --header "PRIVATE-TOKEN: $TOKEN" \
"https://gitlab.example.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID/jobs" \
| jq '.[] | {name, stage, duration, queued_duration}'
duration が大きいジョブは実行そのものが重く、queued_duration が大きい場合はRunnerの台数や同時実行数が不足している可能性があります。
この2つを分けて見るだけで、打ち手の方向性が大きく変わります。
数値を数回分並べ、ばらつきも含めて把握しておくと、後で改善効果を検証できます。
依存関係の再取得とビルドの重複が遅延を生む理由
GitLab CI/CDでは、各ジョブが原則として独立した環境で実行されます。
前のジョブで npm ci や pip install を済ませていても、次のジョブには何も引き継がれません。
その結果、同じ依存パッケージのダウンロードとインストールを、ジョブの数だけ繰り返すことになります。
同様に、ビルド済みの成果物を後続のテストやデプロイのジョブが必要とするのに、それを受け渡す手段がなければ、各ジョブで再ビルドが走ります。
計算量の観点で言えば、本来は1回で済む処理をジョブ数分に膨らませているわけです。
代表的な重複パターンを整理すると、次のようになります。
| 重複している処理 | 主な症状 | 改善の方向性 |
|---|---|---|
| 依存パッケージの取得 | 各ジョブの冒頭で毎回ダウンロードが走る | キャッシュで再利用する |
| ビルドの再実行 | テストやデプロイのジョブ内で再びビルドされる | アーティファクトで引き渡す |
| ベースイメージの取得 | ジョブ開始までの待ち時間が長い | 軽量イメージやレイヤー再利用を検討する |
ここで重要なのは、依存関係の再利用と成果物の引き渡しは、目的が異なるという点です。
前者は「あれば速くなる」最適化、後者は「なければ動かない」前提条件です。
この区別が曖昧なまま設計すると、次章以降で扱うキャッシュとアーティファクトの誤用につながります。
GitLab CI/CDのキャッシュとは?仕組みと基本設定

GitLab CI/CDのキャッシュは、ジョブ間で依存パッケージなどを再利用するための仕組みです。
ジョブの終了時に指定したパスをアーカイブとして保存し、次のジョブやパイプラインの開始時に展開します。
冒頭で触れた「同じ処理を毎回やり直す」問題に対する、最も基本的な解決策と言えます。
ただし、キャッシュは保証のない最適化である点を忘れてはいけません。
Runnerの入れ替えや有効期限、キーの不一致によって、キャッシュは存在しないことがあります。
キャッシュがなくても正しく動作し、あれば速くなる。
この性質を前提に設計するのが原則です。
最小限の設定は、次のようになります。
default:
cache:
key: node-modules
paths:
- node_modules/
なお、キャッシュの対象はプロジェクトのワークディレクトリ配下に限られます。
そのため、npmやpipのようにホームディレクトリへ保存されるキャッシュは、環境変数などで保存先をプロジェクト内に変更する必要があります。
cacheキーの設計とfallback_keysの使い方
キャッシュの効果は、キーの設計でほぼ決まります。
固定文字列のキーでは、依存関係が変わっても古いキャッシュを使い続けてしまいます。
逆に、キーの粒度が細かすぎると、ヒット率が下がって効果が薄れます。
そこで有効なのが、ロックファイルの内容からキーを生成する cache:key:files です。
ファイルの内容が変わったときだけキーが変わるため、依存関係の更新に自動で追従できます。
cache:
key:
files:
- package-lock.json
prefix: $CI_JOB_NAME
paths:
- node_modules/
fallback_keys:
- $CI_DEFAULT_BRANCH-node-modules
fallback_keys は、指定したキーのキャッシュが見つからなかったときに、代わりに探すキーを順に指定する設定です。
ロックファイルが更新された直後でも、直前のキャッシュを土台にして差分だけを取得できます。
ゼロから取得するよりも、はるかに短時間で済みます。
キー設計のポイントを整理します。
- 依存関係の定義ファイルからキーを生成し、内容の変化に追従させる
- prefixでジョブや用途ごとに分け、無関係なキャッシュの混在を避ける
- fallback_keysで、キーが変わった直後のヒット率低下を緩和する
ローカルキャッシュと分散キャッシュの違い
キャッシュの保存先は、Runnerの構成によって変わります。
ここを理解していないと、「手元では効くのに、本番のRunnerでは効かない」という事態に陥ります。
Runnerが1台だけの場合、キャッシュはそのRunnerのローカルディスクに保存されます。
同じRunnerで実行されるジョブには効きますが、別のRunnerに割り当てられると、キャッシュは見つかりません。
Runnerが複数台あるほど、この不一致は頻繁に起こります。
これを解消するのが、S3互換のオブジェクトストレージなどを使った分散キャッシュです。
Runnerの設定でキャッシュの保存先を共有ストレージに向けると、どのRunnerからも同じキャッシュを参照できます。
両者の違いをまとめると、次のとおりです。
| 観点 | ローカルキャッシュ | 分散キャッシュ |
|---|---|---|
| 保存先 | Runnerのローカルディスク | オブジェクトストレージなどの共有ストレージ |
| 共有範囲 | 同じRunnerのジョブのみ | すべてのRunnerで共有可能 |
| 転送コスト | ほぼなし | ダウンロードとアップロードが発生 |
| 向いている構成 | 少数のRunner | 複数台や、オートスケールするRunner |
分散キャッシュは万能ではありません。
ネットワーク越しの転送が発生するため、キャッシュが巨大になるほど、展開時間が節約分を上回る可能性があります。
ヒット率と転送時間のトレードオフを、計測して判断することが重要です。
GitLab CI/CDのアーティファクトとは?用途と設定方法

アーティファクトは、ジョブが生成したファイルやディレクトリをGitLabに保存し、後続のジョブへ引き渡したり、Web画面からダウンロードしたりするための仕組みです。
キャッシュが「あれば速くなる最適化」であるのに対し、アーティファクトはパイプラインの正しさを支える成果物の受け渡しを担います。
たとえば、ビルドジョブで生成したバイナリを、テストやデプロイのジョブが利用する場面を考えてみましょう。
アーティファクトを使えば、各ジョブでの再ビルドが不要になります。
前章で触れた「ビルドの重複」を解消する、直接的な手段です。
主な用途は次のとおりです。
- ビルド成果物(バイナリ、バンドル、ドキュメントなど)を後続ジョブへ引き渡す
- テスト結果やカバレッジのレポートを保存し、マージリクエスト上で確認できるようにする
- 障害調査のために、ログやスクリーンショットをジョブ終了後も残す
キャッシュと異なり、アーティファクトはジョブの成功と紐づいて保存され、後続のジョブに確実に渡されます。
この確実性こそが、両者を使い分ける最大の根拠になります。
artifacts:pathsとexpire_inの基本
最も基本的な設定は、保存対象を指定する artifacts:paths と、保存期間を指定する expire_in の組み合わせです。
build:
stage: build
script:
- npm run build
artifacts:
paths:
- dist/
expire_in: 1 week
paths にはプロジェクトのワークディレクトリからの相対パスを指定します。
ここで注意したいのは、保存対象を必要最小限に絞ることです。
node_modules/ のような巨大なディレクトリを含めると、アップロードとダウンロードの時間が増え、かえってパイプラインが遅くなります。
expire_in を省略した場合は、インスタンス全体の既定の有効期限が適用されます。
設定を明示しなければ、不要な成果物が長期間ストレージを占有し続ける可能性があります。
用途に応じて期限を決めておくと安心です。
- 後続ジョブへの受け渡しだけが目的なら、数時間から1日程度の短い期限で十分
- リリース用の成果物やレポートなど、後から参照したいものは、1週間から数か月程度に設定する
また、失敗したジョブのログやスクリーンショットを残したい場合は、when: always や when: on_failure を組み合わせます。
既定では成功したジョブのアーティファクトだけが保存される点も、覚えておくとよいでしょう。
dependenciesとneedsによる受け渡しの制御
アーティファクトは、既定では前のステージにあるすべてのジョブから後続のジョブへ渡されます。
ジョブが増えるほど、不要なアーティファクトのダウンロードが積み重なり、準備時間を圧迫します。
そこで、受け取るアーティファクトを明示的に制御します。
方法は主に2つあります。
test:
stage: test
dependencies:
- build
script:
- npm test
deploy:
stage: deploy
needs:
- job: build
artifacts: true
script:
- ./deploy.sh
dependencies は、アーティファクトを取得する対象のジョブを絞り込む設定です。
空のリストを指定すれば、アーティファクトを一切取得しなくなります。
一方の needs は、ジョブ間の依存関係を宣言し、前のステージの完了を待たずに実行を開始できるようにする設定です。
artifacts: true を併用すれば、依存先のアーティファクトも取得できます。
両者の違いを整理します。
| 設定 | 主な役割 | ステージ待ちの挙動 | 使いどころ |
|---|---|---|---|
| dependencies | 取得するアーティファクトの絞り込み | ステージの順序に従う | 不要な取得を減らしたいとき |
| needs | ジョブ間の依存関係の宣言 | 依存先の完了後すぐに開始できる | 待ち時間を短縮したいとき |
なお、needs を使うと dependencies の指定は無視され、取得対象は needs 側で決まります。
目的に応じて、どちらか一方に統一して設計するのが混乱を避けるコツです。
キャッシュとアーティファクトの違いを比較|使い分けの判断基準

ここまでで、キャッシュとアーティファクトそれぞれの仕組みを見てきました。
両者はどちらも「ファイルを保存して別のジョブで使う」という点で似ていますが、設計思想はまったく異なります。
使い分けを誤ると、高速化どころか、パイプラインの不安定化や遅延を招きかねません。
判断の軸はシンプルです。
そのデータがなくてもパイプラインが正しく動くかどうかを自問してください。
なくても動くが、あれば速くなるならキャッシュです。
なければ後続の処理が成立しないならアーティファクトです。
この一つの問いで、大半のケースは決着します。
目的・保存先・保証の有無で整理する
両者の違いを、観点ごとに整理します。
| 観点 | キャッシュ | アーティファクト |
|---|---|---|
| 主な目的 | 依存関係などの再利用による高速化 | 成果物の受け渡しと保存 |
| 保存先 | Runnerのローカル、または共有ストレージ | GitLabのアーティファクトストレージ |
| 存在の保証 | なし(ベストエフォート) | あり(ジョブ成功時に確実に渡される) |
| 主な対象 | node_modules、pipのキャッシュなど | ビルド成果物、テストレポートなど |
| Web画面からの取得 | 不可 | 可能 |
この表で最も重要なのは「存在の保証」の行です。
キャッシュはRunnerの入れ替わりや有効期限、キーの不一致によって、いつでも失われる可能性があります。
プログラミングの世界に置き換えるなら、キャッシュはメモ化やCPUのキャッシュに近い存在です。
ヒットしなくても結果は変わらず、時間だけが変わります。
一方、アーティファクトは関数の戻り値に相当します。
受け取れなければ、後続の処理は成立しません。
この対比を頭に置いておくと、設定を書く際に迷いが減ります。
よくある誤用パターンとその弊害
実際の現場では、次のような誤用がよく見られます。
- ビルド成果物をキャッシュで受け渡し、別のRunnerで実行された途端にテストが失敗する
- 依存パッケージ全体をアーティファクトに含め、アップロードとダウンロードで時間が膨らむ
- 固定文字列のキーでキャッシュを使い続け、古い依存関係のまま動いて原因不明のエラーが出る
- expire_inを設定せず、不要なアーティファクトがストレージを圧迫する
最初の例は、特に注意が必要です。
キャッシュで成果物を受け渡す構成は、同じRunnerで実行されている間は問題なく動くため、不具合に気づきにくいのです。
Runnerを増やしたり、オートスケールを導入したりしたタイミングで突然パイプラインが不安定になり、再現性の低い障害として現れます。
逆に、依存パッケージ全体をアーティファクトにする誤用は、動作こそ正しいものの、性能面で損をします。
アーティファクトはジョブごとにアップロードされ、後続ジョブごとにダウンロードされるためです。
ファイル数が多いディレクトリほど、転送のオーバーヘッドは大きくなります。
これらの誤用に共通するのは、「保証の有無」という性質を意識せずに設計している点です。
まず役割を決め、その役割に合った仕組みを選ぶ。
この順序を守るだけで、多くの問題は未然に防げます。
【言語別】Node.js・Python・Dockerビルドでのキャッシュ設計例

ここまでで、キャッシュのキー設計や、アーティファクトとの使い分けを整理しました。
本章では、実際のプロジェクトでよく使われる3つの環境について、具体的な設計例を見ていきます。
共通する考え方は、何をキャッシュ対象にするかを、各ツールの挙動から逆算して決めることです。
言語やツールによって、依存関係の保存場所も再利用の単位も異なります。
単に「node_modulesを保存すればよい」と決めつけず、それぞれの特性を踏まえて設計しましょう。
Node.jsのnpm・yarn依存をキャッシュする
Node.jsで悩ましいのは、node_modulesそのものをキャッシュすべきか、パッケージマネージャのダウンロードキャッシュをキャッシュすべきか、という点です。
npm ci は実行のたびにnode_modulesを削除してから再構築します。
そのため、node_modulesを保存しても、その恩恵は受けられません。
有効なのは、ダウンロード済みのパッケージを保持するnpmのキャッシュディレクトリを保存する方法です。
ホームディレクトリ配下のキャッシュはGitLabの保存対象外なので、保存先をプロジェクト内に変更します。
.node-cache:
variables:
npm_config_cache: "$CI_PROJECT_DIR/.npm"
cache:
key:
files:
- package-lock.json
paths:
- .npm/
install:
extends: .node-cache
script:
- npm ci --prefer-offline
--prefer-offline を付けると、キャッシュにあるパッケージを優先して利用し、ネットワークアクセスを減らせます。
yarnを使う場合も考え方は同じで、yarn config set cacheFolder などでキャッシュ先をプロジェクト内に指定し、yarn.lock をキーの生成元にします。
Pythonのpipとvirtualenvをキャッシュする
Pythonでも、保存先をプロジェクト内に寄せる点は共通です。
環境変数 PIP_CACHE_DIR でpipのキャッシュ先を指定し、あわせて仮想環境もプロジェクト内に作成します。
variables:
PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
test:
cache:
key:
files:
- requirements.txt
prefix: $CI_JOB_NAME
paths:
- .cache/pip
- .venv/
script:
- python -m venv .venv
- source .venv/bin/activate
- pip install -r requirements.txt
- pytest
仮想環境まで保存すると、再インストールの時間はさらに短くなります。
ただし、仮想環境はPythonのバージョンやOSに依存するため、異なる環境で作られたものを流用すると不整合が起きかねません。
次の点に注意してください。
- キーにPythonのバージョンや使用するイメージ名を含め、環境が変わったときにキャッシュが分かれるようにする
- 仮想環境の保存が不安なら、まずはpipのダウンロードキャッシュだけに絞る
- ネイティブ拡張を含むパッケージは、ビルド環境の違いで壊れやすいため特に慎重に扱う
Dockerイメージのレイヤーキャッシュを活用する
Dockerイメージのビルドは、ファイル単位のキャッシュとは性質が異なります。
Dockerは、Dockerfileの各命令を「レイヤー」として保存し、命令とその入力が変わらない限り再利用します。
しかし、CIではジョブごとに新しい環境が用意されるため、既定ではレイヤーがまったく残りません。
そこで、ビルドしたイメージ自体をレジストリに保存し、次回のビルドでそれをキャッシュとして参照する方法が有効です。
BuildKitを使う例を示します。
build-image:
image: docker:latest
services:
- docker:dind
script:
- docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
- docker buildx build
--cache-from type=registry,ref=$CI_REGISTRY_IMAGE:cache
--cache-to type=registry,ref=$CI_REGISTRY_IMAGE:cache,mode=max
--tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
--push .
レイヤーキャッシュを効かせるには、Dockerfileの記述順序も重要です。
変更頻度の低い処理を上に、変更頻度の高い処理を下に置きます。
たとえば、依存関係ファイルだけを先にコピーしてインストールを済ませ、その後にソースコード全体をコピーします。
こうすれば、ソースを修正しても依存関係のレイヤーは再利用されます。
三者の違いを整理すると、次のようになります。
| 対象 | キャッシュする単位 | キーの生成元 | 主な注意点 |
|---|---|---|---|
| Node.js | パッケージのダウンロードキャッシュ | package-lock.json | node_modulesの保存は効果が薄い |
| Python | pipキャッシュと仮想環境 | requirements.txt | バージョンやOSの違いに依存する |
| Docker | イメージのレイヤー | Dockerfileと入力ファイル | 命令の順序で再利用率が決まる |
いずれの場合も、まずは効果を計測しながら小さく始めることをおすすめします。
キャッシュが効かない・遅くなる時のトラブルシューティング

キャッシュを導入したのに、期待したほど速くならない。
あるいは、導入前よりかえって遅くなった。
こうした状況は珍しくありません。
キャッシュは保証のない最適化であるため、効いていないことに気づかないまま運用されがちです。
原因を推測で探すのは非効率です。
まずジョブログという一次情報を確認し、「ヒットしていないのか」「ヒットしているが遅いのか」を切り分けましょう。
前者ならキー設計や保存先の問題、後者なら容量や圧縮方式の問題である可能性が高くなります。
キャッシュがヒットしない原因と確認方法
ジョブログの冒頭付近には、キャッシュの探索結果が出力されます。
キャッシュキーの表示、取得に成功したかどうか、展開に成功したかどうかを確認してください。
ここで「見つからなかった」と分かれば、次の観点で原因を絞り込めます。
- キーが毎回変わっている:コミットSHAなど、実行ごとに変わる値をキーに含めていないか確認する
- 保存対象がプロジェクト外にある:ワークディレクトリ配下のパスしか保存できないため、ホームディレクトリ配下のパスは対象外になる
- Runnerが異なる:ローカルキャッシュの構成では、別のRunnerに割り当てられるとキャッシュが見えない
- 保護ブランチとそれ以外で分離されている:共有キャッシュでは、保護ブランチとそれ以外のブランチでキャッシュが別々に管理される
- 前段のジョブが保存していない:キャッシュを作成するジョブがなく、全ジョブが読み取り専用になっている
特に見落としやすいのが、最後の項目です。
キャッシュを作る側と読む側の役割が曖昧だと、全ジョブが取得だけを試みて、誰も保存しない状態になり得ます。
読み取り専用のジョブには cache:policy: pull を指定し、依存関係を更新するジョブだけが保存する構成にすると、役割が明確になります。
lint:
cache:
key:
files:
- package-lock.json
paths:
- .npm/
policy: pull
script:
- npm run lint
pullを指定したジョブは、ジョブ終了時のアップロード処理を省略できます。
ヒット率の改善だけでなく、無駄な転送の削減にもつながる設定です。
キャッシュの展開・圧縮に時間がかかる場合の対処
キャッシュがヒットしているのに遅い場合は、展開とアップロードの時間を疑います。
ジョブログに、キャッシュの展開だけで数十秒から数分かかっている記録があれば、該当します。
キャッシュ効果が転送コストに食われている状態です。
対処の基本方針は、保存するデータ量とファイル数を減らすことです。
特に、小さなファイルが数万個ある構成は、圧縮と展開の負荷が大きくなります。
- 不要なディレクトリを保存対象から外し、ダウンロード済みパッケージなど再利用価値の高いものに絞る
- 保存してよいか判断が難しいジョブは、ジョブごとにキャッシュを分割し、必要なものだけ取得する
- Runnerの機能フラグ
FF_USE_FASTZIPを有効にし、高速な圧縮ライブラリを使う - 圧縮レベルを
CACHE_COMPRESSION_LEVELで調整し、圧縮率と処理時間のバランスを取る
圧縮レベルはトレードオフの関係にあります。
| 圧縮レベル | 処理時間 | データサイズ | 向いているケース |
|---|---|---|---|
| 低い | 短い | 大きい | 転送が高速で、CPU時間を節約したい環境 |
| 高い | 長い | 小さい | 転送が低速で、通信量を減らしたい環境 |
どちらが最適かは環境次第ですので、実測して決めるのが確実です。
アーティファクトの肥大化を防ぐ
アーティファクトも、大きくなりすぎれば遅延とストレージ圧迫の原因になります。
後続ジョブごとにダウンロードされるため、サイズの影響はキャッシュ以上に積み重なります。
まず有効なのが、artifacts:exclude による除外です。
pathsで広い範囲を指定しつつ、不要なファイルを明示的に除きます。
build:
artifacts:
paths:
- dist/
exclude:
- dist/**/*.map
- dist/**/*.log
あわせて、次の点も見直してください。
- 保存対象を、後続ジョブが実際に使うファイルだけに絞る
- 圧縮レベルを
ARTIFACT_COMPRESSION_LEVELで調整する - 受け取り不要なジョブには、空の
dependenciesを指定して取得を止める - プロジェクトの設定で、既定の有効期限を短めに設定しておく
なお、untracked: true は、Gitの管理外のファイルをすべて保存対象にします。
意図せずキャッシュ用のディレクトリまで含まれ、サイズが急増する事例が少なくありません。
使う場合は、何が対象になるかを必ず確認しましょう。
トラブルシューティングの基本は、ログで事実を確認し、仮説を一つずつ検証することです。
計測、原因の特定、修正、再計測という流れを守れば、キャッシュとアーティファクトは安定して効果を発揮します。
実行時間をさらに短縮する運用設計|並列化・rules・DAG

キャッシュとアーティファクトを適切に使い分けても、パイプラインの構造そのものに無駄があれば、実行時間は思うように縮みません。
前章までは「1つのジョブを速くする」話でしたが、本章では視点を変え、パイプライン全体の待ち時間を減らす設計を扱います。
パイプラインの所要時間は、依存関係の連なりのうち最も長い経路、つまりクリティカルパスで決まります。
したがって、短縮の方針は次の3つに整理できます。
- 待たなくてよい待ち時間をなくす(DAG化)
- 走らせなくてよいジョブを走らせない(条件付き実行)
- ジョブが実行される土台を整える(Runnerとストレージ)
needsによるDAG化でステージ待ちを削減
既定のGitLab CI/CDでは、あるステージのジョブがすべて完了するまで、次のステージは始まりません。
たとえば、フロントエンドのビルドが1分で終わっても、バックエンドのビルドに10分かかれば、フロントエンドのテストは10分待たされます。
ステージという粗い単位で同期を取っているために生じる無駄です。
needs を使うと、ジョブ間の依存関係を有向非巡回グラフ(DAG)として宣言でき、依存先が終わった時点で後続ジョブを即座に開始できます。
stages:
- build
- test
build-frontend:
stage: build
script:
- npm run build
build-backend:
stage: build
script:
- ./gradlew assemble
test-frontend:
stage: test
needs: ["build-frontend"]
script:
- npm test
test-backend:
stage: test
needs: ["build-backend"]
script:
- ./gradlew test
この構成では、test-frontendはbuild-backendの完了を待ちません。
依存関係のないジョブ同士が並行して進むため、クリティカルパスだけが全体の所要時間を決めるようになります。
なお、needsで指定した依存先のアーティファクトは既定で取得されます。
成果物が不要な依存であれば、artifacts: false を指定して無駄なダウンロードを省けます。
DAGの効果は、依存関係の粒度を正しく表現できるほど大きくなります。
rulesとchangesで不要なジョブを走らせない
最も速いジョブは、実行されないジョブです。
フロントエンドのみを修正したコミットで、バックエンドの重いテストまで毎回走らせる必要はありません。
rules:changes を使えば、特定のファイルが変更されたときだけジョブを実行できます。
test-backend:
script:
- ./gradlew test
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
changes:
paths:
- backend/**/*
- build.gradle
compare_to: refs/heads/main
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
マージリクエストでは変更があった場合のみ実行し、デフォルトブランチでは常に実行する構成です。
重要なのは、省略の安全性を設計で担保することです。
差分ベースの判定は、共通ライブラリや設定ファイルの変更を見落とすと、本来走るべきテストが抜け落ちます。
依存する共有ファイルもchangesの対象に含め、デフォルトブランチで全ジョブを走らせる網羅的な検証を残しておくと安心です。
実行条件の設計は、速度と検証の網羅性のトレードオフです。
次のように整理できます。
| 実行タイミング | 実行するジョブ | 狙い |
|---|---|---|
| マージリクエスト | 変更に関係するジョブのみ | フィードバックを速くする |
| デフォルトブランチ | すべてのジョブ | 見落としを検出する |
| スケジュール実行 | 重い統合テストなど | 通常の開発速度を落とさない |
Runnerの構成とストレージ設計を見直す
ここまでの最適化も、Runnerの資源が不足していれば効果が半減します。
ジョブが並列に実行できる構造になっても、Runnerの同時実行数が足りなければ、キュー待ちが新たなボトルネックになるためです。
冒頭で触れたduration とqueued_durationを分けて見る方法で、待ち時間の内訳を継続的に確認しましょう。
Runnerの設定は config.toml で行います。
同時実行数と、複数台で共有する分散キャッシュの保存先を指定する例です。
concurrent = 10
[[runners]]
name = "shared-runner"
executor = "docker"
[runners.cache]
Type = "s3"
Shared = true
[runners.cache.s3]
ServerAddress = "s3.amazonaws.com"
BucketName = "ci-cache"
BucketLocation = "ap-northeast-1"
concurrent は同時に実行できるジョブ数の上限です。
単純に増やせばよいわけではなく、ホストのCPUやメモリ、ディスクI/Oを使い切ると、かえって個々のジョブが遅くなります。
実測しながら調整するのが基本です。
ストレージ面では、次の点も見直してください。
- Runnerとキャッシュ用ストレージを同じリージョンに置き、転送の遅延を抑える
- ビルド用のディスクにはI/O性能の高いものを使い、小さなファイルの展開時間を短縮する
- キャッシュとアーティファクトに有効期限を設け、ストレージの肥大化を防ぐ
- ジョブの性質に応じてRunnerにタグを付け、重いジョブと軽いジョブの資源競合を避ける
パイプラインの構造、実行条件、実行基盤の3層は、互いに影響し合います。
一度にすべてを変えるのではなく、計測して最大のボトルネックから順に改善する。
この地道な繰り返しが、実行時間を確実に縮める近道です。
まとめ|GitLab CI/CDの高速化はキャッシュとアーティファクトの使い分けから

本記事では、GitLab CI/CDの実行時間が長くなる原因を、計測、キャッシュ、アーティファクト、パイプライン構造の順に整理してきました。
冒頭で述べたとおり、遅さの根本にあるのは、ジョブそのものの重さよりも、同じ処理を毎回ゼロからやり直す設計です。
依存関係の再取得とビルドの重複を取り除けば、実行時間は大きく改善します。
その中心となる考え方は、そのデータがなくてもパイプラインが正しく動くかどうかという一つの問いです。
なくても動くが、あれば速くなるものはキャッシュに、なければ後続の処理が成立しないものはアーティファクトに割り当てます。
この保証の有無という軸を持っておけば、設定に迷う場面は大幅に減ります。
各章の要点を、課題ごとに振り返ります。
| 課題 | 使う仕組み | 設計のポイント |
|---|---|---|
| 依存パッケージの再取得 | キャッシュ | ロックファイルからキーを生成し、fallback_keysでヒット率の低下を緩和する |
| ビルド成果物の受け渡し | アーティファクト | 対象を絞り、expire_inで保存期間を明示する |
| ステージ待ちによる遅延 | needsによるDAG化 | クリティカルパスだけが全体の所要時間を決める構造にする |
| 不要なジョブの実行 | rulesとchanges | 省略の安全性を担保するため、デフォルトブランチでは全体を検証する |
| キュー待ちと転送の遅延 | Runnerと共有ストレージの見直し | durationとqueued_durationを分けて継続的に確認する |
実際に取り組む際は、次の順序をおすすめします。
効果が大きく、リスクの小さいものから着手するのが合理的です。
- ジョブごとのdurationとqueued_durationを計測し、ボトルネックを特定する
- 依存パッケージのキャッシュを導入し、ジョブログでヒットを確認する
- 成果物の受け渡しをアーティファクトに移し、保存対象と有効期限を絞る
- needsとrulesで、待ち時間と不要なジョブを削減する
- Runnerの同時実行数とストレージ構成を、実測をもとに調整する
ここで強調したいのは、最適化は一度きりの作業ではなく、継続的な改善サイクルだという点です。
コードベースが成長すれば依存関係もテストの量も増え、かつて効果的だった設定が、いつの間にか最適でなくなることがあります。
計測、仮説、修正、再計測を繰り返し、数値で効果を確認する習慣をつけましょう。
また、キャッシュやアーティファクトは、増やせば増やすほど速くなるものではありません。
保存と展開にも時間がかかるため、対象を欲張ると転送コストが節約分を上回ります。
小さく始めて、効果を確認しながら広げる。
この慎重さが、安定した高速化につながります。
パイプラインが緑になるまでの待ち時間が短くなれば、開発者は文脈を保ったままフィードバックを得られ、開発の質と速度の両方が向上します。
まずはご自身のプロジェクトで、どのジョブに最も時間がかかっているかを確認するところから始めてみてはいかがでしょうか。
その一歩が、実行時間の大きな短縮につながります。


コメント