Add latest changes from gitlab-org/gitlab@master

2 files changed, 25 insertions, 22 deletions

diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md
index a2944a708eb..81e13192cef 100644
--- a/doc/ci/troubleshooting.md
+++ b/doc/ci/troubleshooting.md
@@ -40,29 +40,8 @@ is at:
 https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/editor/schema/ci.json.
 ```
 
-The schema rules for custom YAML tags like `!reference` are treated as invalid by your editor until the custom tags are
-set in your editor settings. For example:
-
-- In VS Code, you can set `vscode-yaml` to parse `customTags` in your `settings.json` file:
-
-  ```json
-  "yaml.customTags": [
-     "!reference sequence"
-  ]
-  ```
-
-- In Sublime Text, if you are using the `LSP-yaml` package, you can set `customTags` in your `LSP-yaml` user settings:
-
-  ```json
-  {
-    "settings": {
-      "yaml.customTags": ["!reference sequence"]
-    }
-  }
-  ```
-
 To see the full list of custom tags covered by the CI/CD schema, check the
-latest version of the schema, linked above.
+latest version of the schema.
 
 ### Verify syntax with CI Lint tool
 
diff --git a/doc/ci/yaml/yaml_optimization.md b/doc/ci/yaml/yaml_optimization.md
index f4774619713..5344a999b95 100644
--- a/doc/ci/yaml/yaml_optimization.md
+++ b/doc/ci/yaml/yaml_optimization.md
@@ -473,3 +473,27 @@ nested-references:
 ```
 
 In this example, the `nested-references` job runs all three `echo` commands.
+
+### Configure your IDE to support `!reference` tags
+
+The [pipeline editor](../pipeline_editor/index.md) supports `!reference` tags. However, the schema rules for custom YAML
+tags like `!reference` might be treated as invalid by your editor by default.
+You can configure some editors to accept `!reference` tags. For example:
+
+- In VS Code, you can set `vscode-yaml` to parse `customTags` in your `settings.json` file:
+
+  ```json
+  "yaml.customTags": [
+     "!reference sequence"
+  ]
+  ```
+
+- In Sublime Text, if you are using the `LSP-yaml` package, you can set `customTags` in your `LSP-yaml` user settings:
+
+  ```json
+  {
+    "settings": {
+      "yaml.customTags": ["!reference sequence"]
+    }
+  }
+  ```