Using Git submodules with GitLab CI/CD (FREE)
Use Git submodules to keep a Git repository as a subdirectory of another Git repository. You can clone another repository into your project and keep your commits separate.
When you use Git submodules, your project should have a file named
You might need to modify it to work in a GitLab CI/CD job.
For example, your
.gitmodules configuration might look like the following if:
- Your project is located at
- Your project depends on
https://gitlab.com/group/project, which you want to include as a submodule.
- You check out your sources with an SSH address like
[submodule "project"] path = project url = ../../group/project.git
When your submodule is on the same GitLab server, you should use relative URLs in
.gitmodules file. Then you can clone with HTTPS in all your CI/CD jobs. You
can also use SSH for all your local checkouts.
The above configuration instructs Git to automatically deduce the URL to use when cloning sources. Git uses the same configuration for both HTTPS and SSH. GitLab CI/CD uses HTTPS for cloning your sources, and you can continue to use SSH to clone locally.
For submodules not located on the same GitLab server, use the full URL:
[submodule "project-x"] path = project-x url = https://gitserver.com/group/project-x.git
Use Git submodules in CI/CD jobs
To make submodules work correctly in CI/CD jobs:
Make sure you use relative URLs for submodules located in the same GitLab server.
You can set the
GIT_SUBMODULE_STRATEGYvariable to either
recursiveto tell the runner to fetch your submodules before the job:
variables: GIT_SUBMODULE_STRATEGY: recursive
GIT_SUBMODULE_DEPTHto configure the cloning depth of submodules independently of the
variables: GIT_SUBMODULE_DEPTH: 1
You can filter or exclude specific submodules to control which submodules will be synced using
variables: GIT_SUBMODULE_PATHS: submoduleA submoduleB
You can provide additional flags to control advanced checkout behavior using
variables: GIT_SUBMODULE_STRATEGY: recursive GIT_SUBMODULE_UPDATE_FLAGS: --jobs 4
If you use the
CI_JOB_TOKEN to clone a submodule in a
pipeline job, the user executing the job must be assigned to a role that has
permission to trigger a pipeline
in the upstream submodule project.
Can't find the
.gitmodules file might be hard to find because it is usually a hidden file.
You can check documentation for your specific OS to learn how to find and display
If there is no
.gitmodules file, it's possible the submodule settings are in a
git config file.
fatal: run_command returned non-zero status error
This error can happen in a job when working with submodules and the
GIT_STRATEGY is set to
clone should resolve the issue.