GitLab CI/CD를 사용하여 Git 서브모듈 사용하기

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

Git 서브모듈을 사용하여 Git 리포지터리를 다른 Git 리포지터리의 하위 디렉터리로 유지합니다. 다른 리포지터리를 프로젝트에 Merge하고 커밋을 분리하여 유지할 수 있습니다.

.gitmodules 파일 구성

Git 서브모듈을 사용할 때, 프로젝트에 .gitmodules라는 파일이 있어야 합니다. GitLab CI/CD 작업에서 이 파일을 구성하는 여러 옵션이 있습니다.

절대 URL 사용

  • 소개됨: GitLab Runner 15.11.

예를 들어, 생성된 .gitmodules 구성은 다음과 같을 수 있습니다:

  • 여러분의 프로젝트가 https://gitlab.com/secret-group/my-project에 위치해 있고,
  • 여러분의 프로젝트가 서브모듈로 포함하고자 하는 https://gitlab.com/group/project에 의존하며,
  • 여러분이 SSH 주소로 소스를 체크아웃하는 경우 git@gitlab.com:secret-group/my-project.git. 
[submodule "project"]
  path = project
  url = git@gitlab.com:secret-group/project.git

이 경우, 서브모듈을 복제하기 전에 URL을 HTTPS로 변환하도록 GIT_SUBMODULE_FORCE_HTTPS 변수를 사용하여 GitLab Runner에 지시하세요.

또는 로컬에서도 HTTPS를 사용하는 경우 HTTPS URL을 구성할 수 있습니다: 

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

이 경우 별도의 변수를 구성할 필요는 없지만, 로컬에서 복제하려면 개인 액세스 토큰을 사용해야 합니다.

상대 URL 사용

caution
상대 URL을 사용하는 경우 Forking Workflows에서 서브모듈이 잘못 해석될 수 있습니다. 프로젝트가 포크될 것으로 예상된다면 대신에 절대 URL을 사용하세요.

서브모듈이 동일한 GitLab 서버에 있는 경우, .gitmodules 파일에서도 상대 URL을 사용할 수 있습니다: 

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

위의 구성은 Git이 소스를 복제할 때 사용할 URL을 자동으로 추측하도록 지시합니다. 모든 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/CD 작업 토큰 액세스가 제대로 구성되어 있어야 합니다.

문제 해결

.gitmodules 파일을 찾을 수 없음

.gitmodules 파일을 찾기 어려울 수 있습니다. 보통 숨겨진 파일이기 때문입니다. 특정 OS에 대한 문서를 확인하여 숨겨진 파일을 찾고 표시하는 방법을 알아보세요.

만약 .gitmodules 파일이 없다면, 서브모듈 설정이 git config 파일에 있을 수 있습니다.

fatal: run_command returned non-zero status 오류

이 오류는 서브모듈을 사용하고 GIT_STRATEGY가 fetch로 설정된 작업에서 발생할 수 있습니다.

GIT_STRATEGY를 clone으로 설정하면 이 문제가 해결될 수 있습니다.