1 files changed, 33 insertions, 2 deletions
diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md
index 5750fe1ba61..4fc52995fc1 100644
--- a/doc/ci/yaml/script.md
+++ b/doc/ci/yaml/script.md
@@ -121,10 +121,10 @@ 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 variables, or even [custom environment variables](../variables/README.md#custom-cicd-variables),
+You can define the color codes in Shell environment variables, or even [custom CI/CD variables](../variables/README.md#custom-cicd-variables),
 which makes the commands easier to read and reusable.
 
-For example, using the same example as above and variables defined in a `before_script`:
+For example, using the same example as above and environment variables defined in a `before_script`:
 
 ```yaml
 job:
@@ -145,3 +145,34 @@ job:
     - Write-Host $TXT_RED"This text is red,"$TXT_CLEAR" but this text isn't"$TXT_RED" however this text is red again."
     - Write-Host "This text is not colored"
 ```
+
+## Troubleshooting
+
+### `Syntax is incorrect` in scripts that use `:`
+
+If you use a colon (`:`) in a script, GitLab might output:
+
+- `Syntax is incorrect`
+- `script config should be a string or a nested array of strings up to 10 levels deep`
+
+For example, if you use `"PRIVATE-TOKEN: ${PRIVATE_TOKEN}"` as part of a cURL command:
+
+```yaml
+pages-job:
+  stage: deploy
+  script:
+    - curl --header 'PRIVATE-TOKEN: ${PRIVATE_TOKEN}' "https://gitlab.example.com/api/v4/projects"
+```
+
+The YAML parser thinks the `:` defines a YAML keyword, and outputs the
+`Syntax is incorrect` error.
+
+To use commands that contain a colon, you should wrap the whole command
+in single quotes. You might need to change existing single quotes (`'`) into double quotes (`"`):
+
+```yaml
+pages-job:
+  stage: deploy
+  script:
+    - 'curl --header "PRIVATE-TOKEN: ${PRIVATE_TOKEN}" "https://gitlab.example.com/api/v4/projects"'
+```