diff options
| -rw-r--r-- | doc/ci/git_submodules.md | 13 | ||||
| -rw-r--r-- | doc/ci/yaml/README.md | 35 |
2 files changed, 47 insertions, 1 deletions
diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index 1d782200cca..869743ce80a 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -61,7 +61,18 @@ correctly with your CI builds: 1. First, make sure you have used [relative URLs](#configuring-the-gitmodules-file) for the submodules located in the same GitLab server. -1. Then, use `git submodule sync/update` in `before_script`: +1. Next, if you are using `gitlab-ci-multi-runner` v1.10+, you can set the + `GIT_SUBMODULE_STRATEGY` variable to either `normal` or `recursive` to tell + the runner to fetch your submodules before the build: + ```yaml + variables: + GIT_SUBMODULE_STRATEGY: recursive + ``` + See the [`.gitlab-ci.yml` reference](yaml/README.md#git-submodule-strategy) + for more details about `GIT_SUBMODULE_STRATEGY`. + +1. If you are using an older version of `gitlab-ci-multi-runner`, then use + `git submodule sync/update` in `before_script`: ```yaml before_script: diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 7158b2e7895..75a0897eb15 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -1034,6 +1034,41 @@ variables: GIT_STRATEGY: none ``` +## Git Submodule Strategy + +> Requires GitLab Runner v1.10+. + +The `GIT_SUBMODULE_STRATEGY` variable is used to control if / how Git +submodules are included when fetching the code before a build. Like +`GIT_STRATEGY`, it can be set in either the global [`variables`](#variables) +section or the [`variables`](#job-variables) section for individual jobs. + +There are three posible values: `none`, `normal`, and `recursive`: + +- `none` means that submodules will not be included when fetching the project + code. This is the default, which matches the pre-v1.10 behavior. + +- `normal` means that only the top-level submodules will be included. It is + equivalent to: + ``` + $ git submodule sync + $ git submodule update --init + ``` + +- `recursive` means that all submodules (including submodules of submodules) + will be included. It is equivalent to: + ``` + $ git submodule sync --recursive + $ git submodule update --init --recursive + ``` + +Note that for this feature to work correctly, the submodules must be configured +(in `.gitmodules`) with either: +- the HTTP(S) URL of a publicly-accessible repository, or +- a relative path to another repository on the same GitLab server. See the + [Git submodules](../git_submodules.md) documentation. + + ## Build stages attempts > Introduced in GitLab, it requires GitLab Runner v1.9+. |