Merge branch 'add-edge-cases-to-include-documentation' into 'master'

Document edge cases for gitlab-ci.yml `include` keyword

Closes #5025 and #5028

See merge request gitlab-org/gitlab-ee!4711

doc/ci/yaml/README.md

@@ -367,7 +367,7 @@ skip the download step.
 
 Using the `include` keyword, you can allow the inclusion of external YAML files.
 
-In the following example, the content of`.before-script-template.yml` will be
+In the following example, the content of `.before-script-template.yml` will be
 automatically fetched and evaluated along with the content of `.gitlab-ci.yml`:
 
 ```yaml
@@ -424,6 +424,9 @@ include:
     your configuration file is. In other words, when using a **local file**, make
     sure that both `.gitlab-ci.yml` and the local file are on the same branch.
 
+    NOTE: **Note:**
+    We don't support the inclusion of local files through Git submodules paths.
+
 - **remote** in a different location, accessed using HTTP/HTTPS, referenced
   using the full URL. For example:
 
@@ -431,6 +434,9 @@ include:
     include: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'
     ```
 
+    NOTE: **Note:**
+    The remote file must be publicly accessible through a simple GET request, as we don't support authentication schemas in the remote URL.
+
 ---
 
 Since external files defined by `include` are evaluated first, the content of
@@ -492,6 +498,9 @@ In this case, the variables `POSTGRES_USER`, `POSTGRES_PASSWORD` and
 `autodevops-template.yml` will be overridden by the ones defined in
 `.gitlab-ci.yml`.
 
+NOTE: **Note:**
+Momentarily the [CI Lint](https://gitlab.com/ci/lint) does not support the `include` keyword.
+
 ## Jobs
 
 `.gitlab-ci.yml` allows you to specify an unlimited number of jobs. Each job