Add troubleshooting details about quoting in CI

Quoting can be important for inputs and variable expressions

doc/ci/jobs/job_control.md

@@ -1218,3 +1218,49 @@ a branch that has an open merge request associated with it.
 To [prevent duplicate pipelines](#avoid-duplicate-pipelines), use
 [`workflow: rules`](../yaml/index.md#workflow) or rewrite your rules to control
 which pipelines can run.
+
+### `This GitLab CI configuration is invalid` for variable expressions
+
+You might receive one of several `This GitLab CI configuration is invalid` errors
+when working with [CI/CD variable expressions](#cicd-variable-expressions).
+These syntax errors can be caused by incorrect usage of quote characters.
+
+In variable expressions, strings should be quoted, while variables should not be quoted.
+For example:
+
+```yaml
+variables:
+  ENVIRONMENT: production
+
+job:
+  script: echo
+  rules:
+    - if: $ENVIRONMENT == "production"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+In this example, both `if:` clauses are valid because the `production` string is quoted,
+and the CI/CD variables are unquoted.
+
+On the other hand, these `if:` clauses are all invalid:
+
+```yaml
+variables:
+  ENVIRONMENT: production
+
+job:
+  script: echo
+  rules:       # These rules all cause YAML syntax errors:
+    - if: ${ENVIRONMENT} == "production"
+    - if: "$ENVIRONMENT" == "production"
+    - if: $ENVIRONMENT == production
+    - if: "production" == "production"
+```
+
+In this example:
+
+- `if: ${ENVIRONMENT} == "production"` is invalid, because `${ENVIRONMENT}` is not valid
+  formatting for CI/CD variables in `if:`.
+- `if: "$ENVIRONMENT" == "production"` is invalid, because the variable is quoted.
+- `if: $ENVIRONMENT == production` is invalid, because the string is not quoted.
+- `if: "production" == "production"` is invalid, because there is no CI/CD variable to compare.

doc/ci/yaml/inputs.md

@@ -233,11 +233,18 @@ Only variables you can [use with the `include` keyword](includes.md#use-variable
 Example:
 
 ```yaml
-$[[ inputs.test | expand_vars ]]
+spec:
+  inputs:
+    test:
+      default: 'test $MY_VAR'
+---
+
+test-job:
+  script: echo $[[ inputs.test | expand_vars ]]
 ```
 
-Assuming the value of `inputs.test` is `test $MY_VAR`, and the variable `$MY_VAR` is unmasked
-with a value of `my value`, then the output would be `test my value`.
+In this example, if `$MY_VAR` is unmasked (exposed in job logs) with a value of `my value`, then the input
+would expand to `test my value`.
 
 #### `truncate`
 
@@ -259,3 +266,56 @@ $[[ inputs.test | truncate(3,5) ]]
 ```
 
 Assuming the value of `inputs.test` is `0123456789`, then the output would be `34567`.
+
+## Troubleshooting
+
+### YAML syntax errors when using `inputs`
+
+[CI/CD variable expressions](../jobs/job_control.md#cicd-variable-expressions)
+in `rules:if` expect a comparison of a CI/CD variable with a string, otherwise
+[a variety of syntax errors could be returned](../jobs/job_control.md#this-gitlab-ci-configuration-is-invalid-for-variable-expressions).
+
+You must ensure that expressions remain properly formatted after input values are
+inserted into the configuration, which might require the use of additional quote characters.
+
+For example:
+
+```yaml
+spec:
+  inputs:
+    branch:
+      default: $CI_DEFAULT_BRANCH
+---
+
+job-name:
+  rules:
+    - if: $CI_COMMIT_REF_NAME == $[[ inputs.branch ]]
+```
+
+In this example:
+
+- Using `include: inputs: branch: $CI_DEFAULT_BRANCH` is valid. The `if:` clause evaluates to
+  `if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH`, which is a valid variable expression.
+- Using `include: inputs: branch: main` is **invalid**. The `if:` clause evaluates to
+  `if: $CI_COMMIT_REF_NAME == main`, which is invalid because `main` is a string but is not quoted.
+
+Alternatively, add quotes to resolve some variable expression issues. For example:
+
+```yaml
+spec:
+  inputs:
+    environment:
+      default: "$ENVIRONMENT"
+---
+
+$[[ inputs.environment | expand_vars ]] job:
+  script: echo
+  rules:
+    - if: '"$[[ inputs.environment1 | expand_vars ]]" == "production"'
+```
+
+In this example, quoting the input block and also the entire variable expression
+ensures valid `if:` syntax after the input is evaluated. The internal and external quotes
+in the expression must not be the same character. You can use `"` for the internal quotes
+and `'` for the external quotes, or the inverse. On the other hand, the job name does
+not require any quoting.