GitLab CI/CD で Git サブモジュールを使う

Git サブモジュールを使うと、Git リポジトリを別の Git リポジトリのサブディレクトリとして管理できます。別のリポジトリをプロジェクトにクローンして、コミットを分けておくことができます。

.gitmodules ファイルの設定

Git サブモジュールを使う場合、プロジェクトには.gitmodules という名前のファイルが必要です。GitLab CI/CDジョブで動作するように設定するには、複数のオプションがあります。

絶対 URL を使う

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

たとえば、生成された.gitmodules の設定は次のようになります：

  • プロジェクトはhttps://gitlab.com/secret-group/my-project にあります。
  • あなたのプロジェクトはhttps://gitlab.com/group/project に依存しており、サブモジュールとしてインクルードする必要があります。
  • git@gitlab.com:secret-group/my-project.git のようなSSHアドレスでソースをチェックアウトします。
[submodule "project"]
  path = project
  url = git@gitlab.com:secret-group/project.git

この場合、GIT_SUBMODULE_FORCE_HTTPS 変数を使って GitLab Runner がサブモジュールをクローンする前に URL を HTTPS に変換するように指示します。

また、ローカルでも HTTPS を使う場合は、HTTPS URL を設定することもできます：

[submodule "project"]
  path = project
  url = https://gitlab.com/secret-group/project.git

この場合、追加の変数を設定する必要はありませんが、ローカルにクローンするには個人アクセストークンを使用する必要があります。

相対URLの使用

caution
相対 URL を使用すると、フォークするワークフローでサブモジュールが正しく解決されないことがあります。プロジェクトがフォークすることを想定している場合は、代わりに絶対 URL を使用してください。

サブモジュールが同じ GitLab サーバー上にある場合は、.gitmodules ファイルで相対 URL を使うこともできます：

[submodule "project"]
  path = project
  url = ../../project.git

上記の設定は、ソースをクローンするときに使う URL を自動的に推測するように Git に指示します。すべての CI/CD ジョブで HTTPS を使ってクローンすることができますし、引き続き SSH を使ってローカルにクローンすることもできます。

同じ GitLab サーバー上にないサブモジュールについては、常に完全な URL を使ってください：

[submodule "project-x"]
  path = project-x
  url = https://gitserver.com/group/project-x.git

CI/CDジョブでGitサブモジュールを使う

CI/CD ジョブでサブモジュールを正しく動作させるには、次のようにします：

  1. GIT_SUBMODULE_STRATEGY 変数をnormal もしくはrecursive に設定することで、ジョブの前にサブモジュールを取得するよう Runner に指示することができます：

    variables:
  GIT_SUBMODULE_STRATEGY: recursive

  2. 同じ GitLab サーバー上にあり、Git または SSH URL で設定されているサブモジュールについては、GIT_SUBMODULE_FORCE_HTTPS 変数を設定してください。

  3. GIT_DEPTH 変数とは別にサブモジュールのクローンの深さを設定するにはGIT_SUBMODULE_DEPTH を使います：

    variables:
  GIT_SUBMODULE_DEPTH: 1

  4. GIT_SUBMODULE_PATHS を使用すると、特定のサブモジュールをフィルタリングまたは除外して、同期するサブモジュールを制御できます。

    variables:
  GIT_SUBMODULE_PATHS: submoduleA submoduleB

  5. GIT_SUBMODULE_UPDATE_FLAGS を使用して、追加のフラグを指定し、高度なチェックアウト動作を制御することができます。

    variables:
  GIT_SUBMODULE_STRATEGY: recursive
  GIT_SUBMODULE_UPDATE_FLAGS: --jobs 4

CI_JOB_TOKEN を使用してパイプラインジョブでサブモジュールをクローンする場合、ジョブを実行するユーザーは、アップストリームサブモジュールプロジェクトでパイプラインをトリガーする権限を持つロールに割り当てられている必要があります。さらに、CI/CDジョブのアクセストークンがアップストリームサブモジュールプロジェクトで適切に設定されている必要があります。

トラブルシューティング

.gitmodules ファイルが見つかりません。

.gitmodules ファイルは通常隠しファイルなので、見つけるのが難しいかもしれません。隠しファイルを見つけ、表示する方法については、お使いのOSのマニュアルをご覧ください。

.gitmodules ファイルがない場合、サブモジュールの設定がgit config ファイルにある可能性があります。

fatal: run_command returned non-zero status エラー

このエラーは、サブモジュールを使用するジョブで、GIT_STRATEGY がfetch に設定されている場合に発生する可能性があります。

GIT_STRATEGY をclone に設定すると、イシューは解決します。