1 files changed, 57 insertions, 1 deletions
diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md
index 1d3186a4047..1c31191c2f4 100644
--- a/doc/ci/yaml/script.md
+++ b/doc/ci/yaml/script.md
@@ -203,7 +203,7 @@ job:
     - echo -e "\e[31mThis text is red,\e[0m but this text isn't\e[31m however this text is red again."
 ```
 
-You can define the color codes in Shell environment variables, or even [custom CI/CD variables](../variables/index.md#custom-cicd-variables),
+You can define the color codes in Shell environment variables, or even [CI/CD variables](../variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file),
 which makes the commands easier to read and reusable.
 
 For example, using the same example as above and environment variables defined in a `before_script`:
@@ -284,3 +284,59 @@ job-fails:
     - (invalid-command xyz && invalid-command abc)
     - echo "The job failed already, and this is not executed."
 ```
+
+### Multiline commands not preserved by folded YAML multiline block scalar
+
+If you use the `- >` folded YAML multiline block scalar to split long commands,
+additional indentation causes the lines to be processed as individual commands.
+
+For example:
+
+```yaml
+script:
+  - >
+    RESULT=$(curl --silent
+      --header
+        "Authorization: Bearer $CI_JOB_TOKEN"
+      "${CI_API_V4_URL}/job"
+    )
+```
+
+This fails as the indentation causes the line breaks to be preserved:
+
+<!-- vale gitlab.CurlStringsQuoted = NO -->
+
+```plaintext
+$ RESULT=$(curl --silent # collapsed multi-line command
+curl: no URL specified!
+curl: try 'curl --help' or 'curl --manual' for more information
+/bin/bash: line 149: --header: command not found
+/bin/bash: line 150: https://gitlab.example.com/api/v4/job: No such file or directory
+```
+
+<!-- vale gitlab.CurlStringsQuoted = YES -->
+
+Resolve this by either:
+
+- Removing the extra indentation:
+
+  ```yaml
+  script:
+    - >
+      RESULT=$(curl --silent
+      --header
+      "Authorization: Bearer $CI_JOB_TOKEN"
+      "${CI_API_V4_URL}/job"
+      )
+  ```
+
+- Modifying the script so the extra line breaks are handled, for example using shell line continuation:
+
+  ```yaml
+  script:
+    - >
+      RESULT=$(curl --silent \
+        --header \
+          "Authorization: Bearer $CI_JOB_TOKEN" \
+        "${CI_API_V4_URL}/job")
+  ```