> - The HTTP(S) Git protocol [must be enabled](../user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols) in your GitLab instance.
## Configuring the `.gitmodules` file
## Configure the `.gitmodules` file
If dealing with [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), your project probably has a file
When you use Git submodules, your project should have a file named `.gitmodules`.
named `.gitmodules`.
You might need to modify it to work in a GitLab CI/CD job.
Let's consider the following example:
For example, your `.gitmodules` configuration might look like the following if:
1. Your project is located at `https://gitlab.com/secret-group/my-project`.
- Your project is located at `https://gitlab.com/secret-group/my-project`.
1. To checkout your sources you usually use an SSH address like
- Your project depends on `https://gitlab.com/group/project`, which you want
`git@gitlab.com:secret-group/my-project.git`.
to include as a submodule.
1. Your project depends on `https://gitlab.com/group/project`, which you want
- You check out your sources with an SSH address like `git@gitlab.com:secret-group/my-project.git`.
to include as a submodule.
If you are using GitLab 8.12+ and your submodule is on the same GitLab server,
you must update your `.gitmodules` file to use **relative URLs**.
Since Git allows the usage of relative URLs for your `.gitmodules` configuration,
this easily allows you to use HTTP(S) for cloning all your CI jobs and SSH
for all your local checkouts. The `.gitmodules` would look like:
```ini
```ini
[submodule "project"]
[submodule "project"]
...
@@ -44,14 +29,16 @@ for all your local checkouts. The `.gitmodules` would look like:
...
@@ -44,14 +29,16 @@ for all your local checkouts. The `.gitmodules` would look like:
url=../../group/project.git
url=../../group/project.git
```
```
The above configuration instructs Git to automatically deduce the URL that
When your submodule is on the same GitLab server, you should use relative URLs in
should be used when cloning sources. Whether you use HTTP(S) or SSH, Git uses
your `.gitmodules` file. Then you can clone with HTTPS in all your CI/CD jobs. You
that same channel and it makes all your CI jobs use HTTP(S).
can also use SSH for all your local checkouts.
GitLab CI/CD only uses HTTP(S) for cloning your sources, and all your local
clones continue using SSH.
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 all other submodules not located on the same GitLab server, use the full
For submodules not located on the same GitLab server, use the full URL:
HTTP(S) protocol URL:
```ini
```ini
[submodule "project-x"]
[submodule "project-x"]
...
@@ -59,45 +46,16 @@ HTTP(S) protocol URL:
...
@@ -59,45 +46,16 @@ HTTP(S) protocol URL:
url=https://gitserver.com/group/project-x.git
url=https://gitserver.com/group/project-x.git
```
```
Once `.gitmodules` is correctly configured, you can move on to
## Use Git submodules in CI/CD jobs
[configuring your `.gitlab-ci.yml`](#using-git-submodules-in-your-ci-jobs).
## Using Git submodules in your CI jobs
There are a few steps you need to take in order to make submodules work
To make submodules work correctly in CI/CD jobs:
correctly with your CI jobs:
1. First, make sure you have used [relative URLs](#configuring-the-gitmodules-file)
1. Make sure you use [relative URLs](#configure-the-gitmodules-file)
for the submodules located in the same GitLab server.
for submodules located in the same GitLab server.
1. Next, if you are using `gitlab-runner` v1.10+, you can set the
1. You can set the `GIT_SUBMODULE_STRATEGY` variable to either `normal` or `recursive`
`GIT_SUBMODULE_STRATEGY` variable to either `normal` or `recursive` to tell
to tell the runner to [fetch your submodules before the job](runners/README.md#git-submodule-strategy):
the runner to fetch your submodules before the job:
```yaml
```yaml
variables:
variables:
GIT_SUBMODULE_STRATEGY:recursive
GIT_SUBMODULE_STRATEGY:recursive
```
```
See the [GitLab Runner documentation](runners/README.md#git-submodule-strategy)
for more details about `GIT_SUBMODULE_STRATEGY`.
1. If you are using an older version of `gitlab-runner`, then use
`git submodule sync/update` in `before_script`:
```yaml
before_script:
-git submodule sync --recursive
-git submodule update --init --recursive
```
`--recursive` should be used in either both or none (`sync/update`) depending on
whether you have recursive submodules.
The rationale to set the `sync` and `update` in `before_script` is because of
the way Git submodules work. On a fresh runner workspace, Git sets the
submodule URL including the token in `.git/config`
(or `.git/modules/<submodule>/config`) based on `.gitmodules` and the current
remote URL. On subsequent jobs on the same runner, `.git/config` is cached
and already contains a full URL for the submodule, corresponding to the previous
job, and to **a token from a previous job**. `sync` allows to force updating
