diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md
index 8827b50190192694c0ee68056e86604df301e299..60b7bec2ba7277c7111812a5c174dc8720037f71 100644
--- a/doc/user/project/new_ci_build_permissions_model.md
+++ b/doc/user/project/new_ci_build_permissions_model.md
@@ -254,6 +254,12 @@ test:
 This will make GitLab CI initialize (fetch) and update (checkout) all your
 submodules recursively.
 
+If Git does not use the newly added relative URLs but still uses your old URLs,
+you might need to add `git submodule sync --recursive` to your `.gitlab-ci.yml`,
+prior to running `git submodule update --init --recursive`. This transfers the
+changes from your `.gitmodules` file into the `.git` folder, which is kept by
+runners between runs.
+
 In case your environment or your Docker image doesn't have Git installed,
 you have to either ask your Administrator or install the missing dependency
 yourself: