Merge branch 'ci-yaml-remove-top' into 'master'

Docs: Removed conceptual info from CI yaml topic

See merge request gitlab-org/gitlab!46391

doc/api/commits.md

@@ -631,7 +631,7 @@ GET /projects/:id/repository/commits/:sha/statuses
 | `sha`     | string  | yes | The commit SHA
 | `ref`     | string  | no  | The name of a repository branch or tag or, if not given, the default branch
 | `stage`   | string  | no  | Filter by [build stage](../ci/yaml/README.md#stages), e.g., `test`
-| `name`    | string  | no  | Filter by [job name](../ci/yaml/README.md#introduction), e.g., `bundler:audit`
+| `name`    | string  | no  | Filter by [job name](../ci/yaml/README.md#job-keywords), e.g., `bundler:audit`
 | `all`     | boolean | no  | Return all statuses, not only the latest ones
 
 ```shell

doc/ci/environments/index.md

@@ -34,8 +34,7 @@ currently being deployed or has been deployed on your servers.
 It's important to know that:
 
 - Environments are like tags for your CI jobs, describing where code gets deployed.
-- Deployments are created when [jobs](../yaml/README.md#introduction) deploy versions of code to environments,
-  so every environment can have one or more deployments.
+- Deployments are created when [GitLab CI/CD](../yaml/README.md) is used to deploy versions of code to environments.
 
 GitLab:
 

doc/ci/examples/end_to_end_testing_webdriverio/index.md

@@ -140,7 +140,7 @@ new browser window interacting with your app as you specified.
 Which brings us to the exciting part: how do we run this in GitLab CI/CD? There are two things we
 need to do for this:
 
-1. Set up [CI/CD jobs](../../yaml/README.md#introduction) that actually have a browser available.
+1. Set up [CI/CD jobs](../../yaml/README.md) that actually have a browser available.
 1. Update our WebdriverIO configuration to use those browsers to visit the review apps.
 
 For the scope of this article, we've defined an additional [CI/CD stage](../../yaml/README.md#stages)

doc/ci/introduction/index.md

@@ -17,6 +17,14 @@ Out-of-the-box management systems can decrease hours spent on maintaining toolch
 Watch our ["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/)
 webcast to learn about continuous methods and how GitLab’s built-in CI can help you simplify and scale software development.
 
+> For some additional information about GitLab CI/CD:
+>
+> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>&nbsp;Watch the [CI/CD Ease of configuration](https://www.youtube.com/embed/opdLqwz6tcE) video.
+> - Watch the [Making the case for CI/CD in your organization](https://about.gitlab.com/compare/github-actions-alternative/)
+>   webcast to learn the benefits of CI/CD and how to measure the results of CI/CD automation.
+> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>&nbsp;Learn how [Verizon reduced rebuilds](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/)
+>   from 30 days to under 8 hours with GitLab.
+
 ## Introduction to CI/CD methodologies
 
 The continuous methodologies of software development are based on

doc/ci/migration/circleci.md

@@ -27,7 +27,7 @@ CircleCI's `config.yml` configuration file defines scripts, jobs, and workflows
 
 ### Jobs
 
-In CircleCI, jobs are a collection of steps to perform a specific task. In GitLab, [jobs](../yaml/README.md#introduction) are also a fundamental element in the configuration file. The `checkout` keyword is not necessary in GitLab CI/CD as the repository is automatically fetched.
+In CircleCI, jobs are a collection of steps to perform a specific task. In GitLab, [jobs](../pipelines/index.md#about-jobs) are also a fundamental element in the configuration file. The `checkout` keyword is not necessary in GitLab CI/CD as the repository is automatically fetched.
 
 CircleCI example job definition:
 

doc/ci/pipelines/index.md

@@ -68,7 +68,7 @@ Pipelines can be configured in many different ways:
 
 Pipelines and their component jobs and stages are defined in the CI/CD pipeline configuration file for each project.
 
-- Jobs are the [basic configuration](../yaml/README.md#introduction) component.
+- Jobs are the [basic configuration](#about-jobs) component.
 - Stages are defined by using the [`stages`](../yaml/README.md#stages) keyword.
 
 For a list of configuration options in the CI pipeline file, see the [GitLab CI/CD Pipeline Configuration Reference](../yaml/README.md).
@@ -287,7 +287,36 @@ preserving deployment keys and other credentials from being unintentionally
 accessed. In order to ensure that jobs intended to be executed on protected
 runners do not use regular runners, they must be tagged accordingly.
 
-## View jobs in a pipeline
+## About jobs
+
+Pipeline configuration begins with jobs. Jobs are the most fundamental element of a `.gitlab-ci.yml` file.
+
+Jobs are:
+
+- Defined with constraints stating under what conditions they should be executed.
+- Top-level elements with an arbitrary name and must contain at least the [`script`](../yaml/README.md#script) clause.
+- Not limited in how many can be defined.
+
+For example:
+
+```yaml
+job1:
+  script: "execute-script-for-job1"
+
+job2:
+  script: "execute-script-for-job2"
+```
+
+The above example is the simplest possible CI/CD configuration with two separate
+jobs, where each of the jobs executes a different command.
+Of course a command can execute code directly (`./configure;make;make install`)
+or run a script (`test.sh`) in the repository.
+
+Jobs are picked up by [runners](../runners/README.md) and executed within the
+environment of the runner. What is important is that each job is run
+independently from each other.
+
+### View jobs in a pipeline
 
 When you access a pipeline, you can see the related jobs for that pipeline.
 

doc/ci/quick_start/README.md

@@ -13,7 +13,12 @@ GitLab offers a [continuous integration](https://about.gitlab.com/stages-devops-
 - Add a [`.gitlab-ci.yml` file](#creating-a-gitlab-ciyml-file) to your repository's root directory.
 - Ensure your project is configured to use a [runner](#configuring-a-runner).
 
-The `.gitlab-ci.yml` file tells the runner what to do. A simple pipeline commonly has
+The `.gitlab-ci.yml` file defines the structure and order of the pipelines, and determines:
+
+- What to execute using [GitLab Runner](https://docs.gitlab.com/runner/).
+- What decisions to make when specific conditions are encountered. For example, when a process succeeds or fails.
+
+A simple pipeline commonly has
 three [stages](../yaml/README.md#stages):
 
 - `build`

doc/ci/troubleshooting.md

@@ -225,7 +225,7 @@ should disable **Pipelines must succeed** so you can accept merge requests.
 
 Pipeline configuration warnings are shown when you:
 
-- [Validate configuration with the CI Lint tool](yaml/README.md#validate-the-gitlab-ciyml).
+- [Validate configuration with the CI Lint tool](yaml/README.md).
 - [Manually run a pipeline](pipelines/index.md#run-a-pipeline-manually).
 
 ### "Job may allow multiple pipelines to run for a single action" warning

doc/ci/yaml/README.md

@@ -7,92 +7,16 @@ type: reference
 
 # GitLab CI/CD pipeline configuration reference
 
-GitLab CI/CD [pipelines](../pipelines/index.md) are configured using a YAML file called `.gitlab-ci.yml` within each project.
+This document lists the configuration options for your GitLab `.gitlab-ci.yml` file.
 
-The `.gitlab-ci.yml` file defines the structure and order of the pipelines and determines:
-
-- What to execute using [GitLab Runner](https://docs.gitlab.com/runner/).
-- What decisions to make when specific conditions are encountered. For example, when a process succeeds or fails.
-
-This topic covers CI/CD pipeline configuration. For other CI/CD configuration information, see:
-
-- [GitLab CI/CD Variables](../variables/README.md), for configuring the environment the pipelines run in.
-- [GitLab Runner advanced configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html), for configuring GitLab Runner.
-
-We have complete examples of configuring pipelines:
-
-- For a quick introduction to GitLab CI/CD, follow our [quick start guide](../quick_start/README.md).
+- For a quick introduction to GitLab CI/CD, follow the [quick start guide](../quick_start/README.md).
 - For a collection of examples, see [GitLab CI/CD Examples](../examples/README.md).
-- To see a large `.gitlab-ci.yml` file used in an enterprise, see the [`.gitlab-ci.yml` file for `gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml).
-
-> For some additional information about GitLab CI/CD:
->
-> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>&nbsp;Watch the [CI/CD Ease of configuration](https://www.youtube.com/embed/opdLqwz6tcE) video.
-> - Watch the [Making the case for CI/CD in your organization](https://about.gitlab.com/compare/github-actions-alternative/)
->   webcast to learn the benefits of CI/CD and how to measure the results of CI/CD automation.
-> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>&nbsp;Learn how [Verizon reduced rebuilds](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/)
->   from 30 days to under 8 hours with GitLab.
-
-If you have a [mirrored repository that GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository),
-you may need to enable pipeline triggering. Go to your project's **Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**.
-
-## Introduction
-
-Pipeline configuration begins with jobs. Jobs are the most fundamental element of a `.gitlab-ci.yml` file.
+- To view a large `.gitlab-ci.yml` file used in an enterprise, see the [`.gitlab-ci.yml` file for `gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml).
 
-Jobs are:
-
-- Defined with constraints stating under what conditions they should be executed.
-- Top-level elements with an arbitrary name and must contain at least the [`script`](#script) clause.
-- Not limited in how many can be defined.
-
-For example:
-
-```yaml
-job1:
-  script: "execute-script-for-job1"
-
-job2:
-  script: "execute-script-for-job2"
-```
-
-The above example is the simplest possible CI/CD configuration with two separate
-jobs, where each of the jobs executes a different command.
-Of course a command can execute code directly (`./configure;make;make install`)
-or run a script (`test.sh`) in the repository.
-
-Jobs are picked up by [runners](../runners/README.md) and executed within the
-environment of the runner. What is important is that each job is run
-independently from each other.
-
-### Validate the `.gitlab-ci.yml`
-
-Each instance of GitLab CI/CD has an embedded debug tool called Lint, which validates the
-content of your `.gitlab-ci.yml` files. You can find the Lint under the page `ci/lint` of your
+While you are authoring your `.gitlab-ci.yml` file, you can validate it
+by using the [CI Lint](../lint.md) tool.
 project namespace. For example, `https://gitlab.example.com/gitlab-org/project-123/-/ci/lint`.
 
-### Unavailable names for jobs
-
-Each job must have a unique name, but there are a few **reserved `keywords` that
-can't be used as job names**:
-
-- `image`
-- `services`
-- `stages`
-- `types`
-- `before_script`
-- `after_script`
-- `variables`
-- `cache`
-- `include`
-
-### Using reserved keywords
-
-If you get validation error when using specific values (for example, `true` or `false`), try to:
-
-- Quote them.
-- Change them to a different form. For example, `/bin/true`.
-
 ## Job keywords
 
 A job is defined as a list of keywords that define the job's behavior.
@@ -130,10 +54,32 @@ The following table lists available keywords for jobs:
 | [`variables`](#variables)                          | Define job variables on a job level.                                                                                                                                                |
 | [`when`](#when)                                    | When to run job. Also available: `when:manual` and `when:delayed`.                                                                                                                  |
 
+### Unavailable names for jobs
+
+Each job must have a unique name, but there are a few **reserved `keywords` that
+can't be used as job names**:
+
+- `image`
+- `services`
+- `stages`
+- `types`
+- `before_script`
+- `after_script`
+- `variables`
+- `cache`
+- `include`
+
 ## Global keywords
 
 Some keywords must be defined at a global level, affecting all jobs in the pipeline.
 
+### Using reserved keywords
+
+If you get validation error when using specific values (for example, `true` or `false`), try to:
+
+- Quote them.
+- Change them to a different form. For example, `/bin/true`.
+
 ### Global defaults
 
 Some keywords can be set globally as the default for all jobs using the

doc/development/integrations/secure.md

@@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 # Security scanner integration
 
 Integrating a security scanner into GitLab consists of providing end users
-with a [CI job definition](../../ci/yaml/README.md#introduction)
+with a [CI job definition](../../ci/yaml/README.md)
 they can add to their CI configuration files to scan their GitLab projects.
 This CI job should then output its results in a GitLab-specified format. These results are then
 automatically presented in various places in GitLab, such as the Pipeline view, Merge Request

doc/user/project/pages/getting_started/pages_from_scratch.md

@@ -158,9 +158,8 @@ When it succeeds, go to **Settings > Pages** to view the URL where your site
 is now available.
 
 If you want to do more advanced tasks, you can update your `.gitlab-ci.yml` file
-with [any of the available settings](../../../../ci/yaml/README.md). See
-[Validate the `.gitlab-ci.yml`](../../../../ci/yaml/README.md#validate-the-gitlab-ciyml)
-for instructions on validating your YAML file with the Lint tool included with GitLab.
+with [any of the available settings](../../../../ci/yaml/README.md). You can validate
+your `.gitlab-ci.yml` file with the [CI Lint](../../../../ci/lint.md) tool that's included with GitLab.
 
 After successful execution of this `pages` job, a special `pages:deploy` job appears in the
 pipeline view. It prepares the content of the website for GitLab Pages daemon. GitLab executes it in