fetch-depth とは？

fetch-depth は、job がどれだけの履歴のコミットをダウンロードするかを制御する CI のチェックアウト設定であり、速度と過去へのアクセスとのトレードオフを調整します。

fetch-depth は、CI の job がどれだけの Git 履歴を取得するかを決めるために回すつまみです。値を小さく設定するとチェックアウトは高速になりますが履歴は浅くなり、すべてを取得するよう設定すると完全なログが得られる代わりに clone が遅くなります。適切な値を選ぶことは、小さくても実際に効く CI の最適化です。

fetch-depth が制御するもの

fetch-depth は clone の depth に直接対応します。depth が 1 の場合、build 対象のコミットだけを取得します。より大きな数値はその数だけの履歴のコミットを取得します。慣例として、depth が 0 の場合はまったく切り詰めずに完全な履歴を取得することを意味します。

fetch-depth の設定

GitHub Actions のチェックアウトでは、fetch-depth はチェックアウト step のパラメータです。

Fetching full history

steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0

より深い depth が必要になるとき

一部の job は最新のコミットを超える履歴を必要とします。base ブランチに対する diff の計算、tag からのバージョン導出、changelog の生成はいずれもコミットをさかのぼって処理します。ツールが履歴の欠落や不明なリビジョンを報告する場合、fetch-depth を増やすのが通常の解決策です。

fetch-depth と CI/CD のパフォーマンス

チェックアウトはすべての job で実行されるため、fetch-depth は大規模なリポジトリでは pipeline 全体の時間に大きな影響を与えます。デフォルトの浅い depth は処理を高速に保ちます。履歴を必要とする特定の job についてのみ引き上げましょう。マネージド runner では、大半の job を浅いままにしておくことで fleet を効率的に保てます。

値の選び方

通常の build や test の job には depth 1（デフォルト）を使いましょう。
changelog、diff、tag からのバージョン取得の step には depth 0 を使いましょう。
実際に履歴を必要とする job でのみ depth を上げましょう。
より深い取得は、それを使うすべての実行を遅くすることを覚えておきましょう。

重要なポイント

fetch-depth は、CI の job がどれだけの履歴のコミットをダウンロードするかを設定します。
depth 0 は完全な履歴を意味し、depth 1 は build のコミットだけを取得します。
速度のために浅く保ち、diff・tag・changelog のためだけに深くしましょう。