Merge branch 'docs-deprecate-new-permissions-doc' into 'master'

Clean up language in git_submodules doc

See merge request gitlab-org/gitlab!55351

doc/ci/git_submodules.md

@@ -5,38 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 type: reference
 ---
 
-# Using Git submodules with GitLab CI
+# Using Git submodules with GitLab CI/CD
 
-> **Notes:**
->
-> - GitLab 8.12 introduced a new [CI job permissions model](../user/project/new_ci_build_permissions_model.md) and you
->   are encouraged to upgrade your GitLab instance if you haven't done already.
->   If you are **not** using GitLab 8.12 or higher, you would need to work your way
->   around submodules in order to access the sources of e.g., `gitlab.com/group/project`
->   with the use of [SSH keys](ssh_keys/index.md).
-> - With GitLab 8.12 onward, your permissions are used to evaluate what a CI job
->   can access. More information about how this system works can be found in the
->   [Jobs permissions model](../user/permissions.md#job-permissions).
-> - 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.
+Use [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to keep
+a Git repository as a subdirectory of another Git repository. You can clone another
+repository into your project and keep your commits separate.
 
-## 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
-named `.gitmodules`.
+When you use Git submodules, your project should have a file 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`.
-1. To checkout your sources you usually use an SSH address like
-   `git@gitlab.com:secret-group/my-project.git`.
-1. Your project depends on `https://gitlab.com/group/project`, which you want
-   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:
+- Your project is located at `https://gitlab.com/secret-group/my-project`.
+- Your project depends on `https://gitlab.com/group/project`, which you want
+  to include as a submodule.
+- You check out your sources with an SSH address like `git@gitlab.com:secret-group/my-project.git`.
 
 ```ini
 [submodule "project"]
@@ -44,14 +29,16 @@ for all your local checkouts. The `.gitmodules` would look like:
   url = ../../group/project.git
 ```
 
-The above configuration instructs Git to automatically deduce the URL that
-should be used when cloning sources. Whether you use HTTP(S) or SSH, Git uses
-that same channel and it makes all your CI jobs use HTTP(S).
-GitLab CI/CD only uses HTTP(S) for cloning your sources, and all your local
-clones continue using SSH.
+When your submodule is on the same GitLab server, you should use relative URLs in
+your `.gitmodules` file. Then you can clone with HTTPS in all your CI/CD jobs. You
+can also use SSH for all your local checkouts.
+
+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
-HTTP(S) protocol URL:
+For submodules not located on the same GitLab server, use the full URL:
 
 ```ini
 [submodule "project-x"]
@@ -59,45 +46,16 @@ HTTP(S) protocol URL:
   url = https://gitserver.com/group/project-x.git
 ```
 
-Once `.gitmodules` is correctly configured, you can move on to
-[configuring your `.gitlab-ci.yml`](#using-git-submodules-in-your-ci-jobs).
-
-## Using Git submodules in your CI jobs
+## Use Git submodules in CI/CD jobs
 
-There are a few steps you need to take in order to make submodules work
-correctly with your CI jobs:
+To make submodules work correctly in CI/CD jobs:
 
-1. First, make sure you have used [relative URLs](#configuring-the-gitmodules-file)
-   for the submodules located in the same GitLab server.
-1. Next, if you are using `gitlab-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 job:
+1. Make sure you use [relative URLs](#configure-the-gitmodules-file)
+   for submodules located in the same GitLab server.
+1. You can set the `GIT_SUBMODULE_STRATEGY` variable to either `normal` or `recursive`
+   to tell the runner to [fetch your submodules before the job](runners/README.md#git-submodule-strategy):
 
    ```yaml
    variables:
      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
-the full URL.

doc/topics/git/index.md

@@ -84,7 +84,7 @@ The following are advanced topics for those who want to get the most out of Git:
 - [Introduction to Git rebase, force-push, and merge conflicts](git_rebase.md)
 - [Server Hooks](../../administration/server_hooks.md)
 - [Git Attributes](../../user/project/git_attributes.md)
-- Git Submodules: [Using Git submodules with GitLab CI](../../ci/git_submodules.md#using-git-submodules-with-gitlab-ci)
+- Git Submodules: [Using Git submodules with GitLab CI](../../ci/git_submodules.md)
 - [Partial Clone](partial_clone.md)
 
 ## API