GitLab CI/CD에서 Git 서브모듈 사용하기
Git submodules을 사용하여 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
에 의존하며, - 소스를 SSH 주소
git@gitlab.com:secret-group/my-project.git
로 확인합니다.
[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 사용
서브모듈이 동일한 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 작업에서 올바르게 작동하려면 다음을 수행하세요:
-
러너에게 서브모듈을 작업 전에 가져오도록
GIT_SUBMODULE_STRATEGY
변수를normal
또는recursive
로 설정합니다(runners/configure_runners.md#git-submodule-strategy):variables: GIT_SUBMODULE_STRATEGY: recursive
-
같은 GitLab 서버에 있는 서브모듈이고 Git 또는 SSH URL로 구성된 경우,
GIT_SUBMODULE_FORCE_HTTPS
변수를 설정하세요. -
GIT_DEPTH
변수와 독립적으로 서브모듈의 복제 깊이를 구성하기 위해GIT_SUBMODULE_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
파이프라인 작업에서 서브모듈을 복제하려면 CI_JOB_TOKEN
을 사용하는 경우, 작업을 실행하는 사용자가 상위 서브모듈 프로젝트에서 파이프라인을 트리거할 권한이 있는 역할에 할당되어 있어야 합니다. 또한, 상위 서브모듈 프로젝트에서 CI/CD 작업 토큰 액세스가 올바르게 구성되어 있어야 합니다.
문제 해결
.gitmodules
파일을 찾을 수 없음
.gitmodules
파일은 일반적으로 숨겨진 파일이기 때문에 찾기 어려울 수 있습니다. 특정 OS에 대한 문서를 확인하여 숨겨진 파일을 찾고 표시하는 방법을 배울 수 있습니다.
.gitmodules
파일이 없는 경우 서브모듈 설정이 git config
파일에 있을 수 있습니다.
fatal: run_command returned non-zero status
오류
이 오류는 서브모듈과 작업 중에 GIT_STRATEGY
가 fetch
로 설정된 경우 발생할 수 있습니다.
GIT_STRATEGY
를 clone
으로 설정하면 문제가 해결됩니다.