GitLab CI/CDでGitサブモジュールを使用する

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

Gitサブモジュールを使用して、Gitリポジトリを別のGitリポジトリのサブディレクトリとして保持します。別のリポジトリのクローンをプロジェクトに作成し、コミットを分離した状態で保持できます。

`.gitmodules`ファイルを設定する

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

絶対URLを使用する

たとえば、以下の条件では、生成される.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:group/project.git

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

または、ローカルでHTTPSも使用する場合は、HTTPS URLを設定できます。

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

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

相対URLを使用する

相対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_JOB_TOKENを使用してサブモジュールのクローンを作成する場合、コードをプルするには、サブモジュールリポジトリに対しレポーター以上のロールが必要です。
CI/CDジョブトークンアクセスは、アップストリームのサブモジュールプロジェクトで適切に設定する必要があります。

CI/CDジョブでサブモジュールを正しく動作させるには、次の手順に従います。

GIT_SUBMODULE_STRATEGY変数をnormalまたはrecursiveのいずれかに設定して、ジョブの前にサブモジュールをフェッチするようにRunnerに指示できます。
```
variables:
  GIT_SUBMODULE_STRATEGY: recursive
```
同じGitLabサーバー上にあり、GitまたはSSH URLで設定されたサブモジュールについては、GIT_SUBMODULE_FORCE_HTTPS変数が設定されていることを確認します。
GIT_SUBMODULE_DEPTHを使用して、GIT_DEPTH変数とは関係なく、サブモジュールのクローンの深さを設定します。
```
variables:
  GIT_SUBMODULE_DEPTH: 1
```
GIT_SUBMODULE_PATHSを使用して、特定のサブモジュールをフィルタリングまたは除外し、同期するサブモジュールを制御できます。
```
variables:
  GIT_SUBMODULE_PATHS: submoduleA submoduleB
```
GIT_SUBMODULE_UPDATE_FLAGSを使用して、追加のフラグを指定し、高度なチェックアウト動作を制御できます。
```
variables:
  GIT_SUBMODULE_STRATEGY: recursive
  GIT_SUBMODULE_UPDATE_FLAGS: --jobs 4
```

トラブルシューティング

`.gitmodules`ファイルが見つからない

通常、.gitmodulesファイルは隠しファイルになっているため、見つけにくい場合があります。隠しファイルを見つけて表示する方法については、対象OSのドキュメントを確認してください。

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

エラー: `fatal: run_command returned non-zero status`

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

GIT_STRATEGYをcloneに設定すると、問題が解決するはずです。

エラー: `fatal: could not read Username for 'https://gitlab.com': No such device or address`

GitLabでホストされているRunnerを使用している場合、CI/CDジョブがGitサブモジュールのクローン作成やGitサブモジュールのフェッチを試みると、このエラーが発生することがあります。

CI/CDパイプラインの実行中に、GitLab RunnerはGit URLの置換を自動的に行い、CI_JOB_TOKENを介して認証します。

git config --global url."https://gitlab-ci-token:${CI_JOB_TOKEN}@${CI_SERVER_FQDN}".insteadOf "${CI_SERVER_FQDN}"

GitLabでホストされているRunnerの場合、CI_SERVER_FQDNはhttps://gitlab.comとは異なります。サブモジュールがhttps://gitlab.comに存在する場合、この置換は実行されず、エラーが発生します。

このエラーを解決する方法の1つは、pre_get_sources_scriptを作成し、CI_JOB_TOKENを使用してURLの置換を手動で設定することです。

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  GIT_SUBMODULE_DEPTH: 1
hooks:
  pre_get_sources_script:
    - git config --global url."https://gitlab-ci-token:${CI_JOB_TOKEN}@${CI_SERVER_FQDN}".insteadOf "${SUBMODULE_URL}"

GitLab CI/CDでGitサブモジュールを使用する

.gitmodulesファイルを設定する