Document GIT_SUBMODULE_STRATEGY

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

[ci skip]

1 files changed, 35 insertions, 0 deletions

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