Document GIT_SUBMODULE_STRATEGY

This documents the `GIT_SUBMODULE_STRATEGY` feature added in
gitlab-ci-multi-runner version 1.10.

[ci skip]

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+.