Merge branch 'docs-ci-lint-ctrt' into 'master'

CTRT revamp of the CI lint doc

See merge request gitlab-org/gitlab!80136

app/views/projects/ci/lints/show.html.haml

@@ -3,4 +3,4 @@
 
 %h4.pt-3.pb-3= _("Validate your GitLab CI configuration")
 
-#js-ci-lint{ data: { endpoint: project_ci_lint_path(@project), pipeline_simulation_help_page_path: help_page_path('ci/lint', anchor: 'pipeline-simulation') , lint_help_page_path: help_page_path('ci/lint', anchor: 'validate-basic-logic-and-syntax') } }
+#js-ci-lint{ data: { endpoint: project_ci_lint_path(@project), pipeline_simulation_help_page_path: help_page_path('ci/lint', anchor: 'simulate-a-pipeline') , lint_help_page_path: help_page_path('ci/lint', anchor: 'check-cicd-syntax') } }

doc/api/lint.md

@@ -169,7 +169,7 @@ POST /projects/:id/ci/lint
 | Attribute  | Type    | Required | Description |
 | ---------- | ------- | -------- | -------- |
 | `content`  | string  | yes      | The CI/CD configuration content. |
-| `dry_run`  | boolean | no       | Run [pipeline creation simulation](../ci/lint.md#pipeline-simulation), or only do static check. This is false by default. |
+| `dry_run`  | boolean | no       | Run [pipeline creation simulation](../ci/lint.md#simulate-a-pipeline), or only do static check. This is false by default. |
 | `include_jobs`  | boolean    | no       | If the list of jobs that would exist in a static check or pipeline simulation should be included in the response. This is false by default. |
 
 Example request:

doc/ci/lint.md

@@ -4,48 +4,54 @@ group: Pipeline Authoring
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# Validate `.gitlab-ci.yml` syntax with the CI Lint tool **(FREE)**
+# Validate GitLab CI/CD configuration **(FREE)**
 
-If you want to test the validity of your GitLab CI/CD configuration before committing
-the changes, you can use the CI Lint tool. This tool checks for syntax and logical
-errors by default, and can simulate pipeline creation to try to find more complicated
-issues as well.
+Use the CI Lint tool to check the validity of GitLab CI/CD configuration.
+You can validate the syntax from a `.gitlab-ci.yml` file or any other sample CI/CD configuration.
+This tool checks for syntax and logic errors, and can simulate pipeline
+creation to try to find more complicated configuration problems.
 
-To access the CI Lint tool, navigate to **CI/CD > Pipelines** or **CI/CD > Jobs**
-in your project and click **CI lint**.
+If you use the [pipeline editor](pipeline_editor/index.md), it verifies configuration
+syntax automatically.
 
-If you use VS Code, you can also validate your CI/CD configuration with the
+If you use VS Code, you can validate your CI/CD configuration with the
 [GitLab Workflow VS Code extension](../user/project/repository/vscode.md).
 
-## Validate basic logic and syntax
+## Check CI/CD syntax
 
-By default, the CI lint checks the syntax of your CI YAML configuration and also runs
-some basic logical validations. Configuration added with the [`includes` keyword](yaml/index.md#include),
-is also validated.
+The CI lint tool checks the syntax of GitLab CI/CD configuration, including
+configuration added with the [`includes` keyword](yaml/index.md#include).
 
-To use the CI lint, paste a complete CI configuration (`.gitlab-ci.yml` for example)
-into the text box and click **Validate**:
+To check CI/CD configuration with the CI lint tool:
 
-![CI Lint](img/ci_lint.png)
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select one of:
+   - **CI/CD > Pipelines**
+   - **CI/CD > Jobs**
+1. In the top right, select **CI lint**.
+1. Paste a copy of the CI/CD configuration you want to check into the text box.
+1. Select **Validate**.
 
-## Pipeline simulation
+## Simulate a pipeline
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229794) in GitLab 13.3.
 
-Not all pipeline configuration issues can be found by the [basic CI lint validation](#validate-basic-logic-and-syntax).
-You can simulate the creation of a pipeline for deeper validation that can discover
-more complicated issues.
-
-To validate the configuration by running a pipeline simulation:
+You can simulate the creation of a GitLab CI/CD pipeline to find more complicated issues,
+including problems with [`needs`](yaml/index.md#needs) and [`rules`](yaml/index.md#rules)
+configuration. A simulation runs as a Git `push` event on the default branch.
 
-1. Paste the GitLab CI configuration to verify into the text box.
-1. Select the **Simulate pipeline creation for the default branch** checkbox.
-1. Select **Validate**.
+Prerequisites:
 
-![Dry run](img/ci_lint_dry_run.png)
+- You must have [permissions](../user/permissions.md#project-members-permissions)
+  to create pipelines on this branch to validate with a simulation.
 
-### Pipeline simulation limitations
+To simulate a pipeline:
 
-Simulations run as `git push` events against the default branch. You must have
-[permissions](../user/permissions.md#project-members-permissions) to create pipelines
-on this branch to validate with a simulation.
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select one of:
+   - **CI/CD > Pipelines**
+   - **CI/CD > Jobs**
+1. In the top right, select **CI lint**.
+1. Paste a copy of the CI/CD configuration you want to check into the text box.
+1. Select **Simulate pipeline creation for the default branch**.
+1. Select **Validate**.

doc/ci/troubleshooting.md

@@ -36,7 +36,7 @@ file is correct. Paste in full `.gitlab-ci.yml` files or individual jobs configu
 to verify the basic syntax.
 
 When a `.gitlab-ci.yml` file is present in a project, you can also use the CI Lint
-tool to [simulate the creation of a full pipeline](lint.md#pipeline-simulation).
+tool to [simulate the creation of a full pipeline](lint.md#simulate-a-pipeline).
 It does deeper verification of the configuration syntax.
 
 ## Verify variables