Copy edit yaml reference to remove passive

Remove as much passive voice as possible
across the whole yaml reference doc

doc/ci/yaml/README.md

@@ -46,7 +46,7 @@ The keywords available for jobs are:
 | [`release`](#release)                              | Instructs the runner to generate a [Release](../../user/project/releases/index.md) object.                                                                                          |
 | [`resource_group`](#resource_group)                | Limit job concurrency.                                                                                                                                                              |
 | [`retry`](#retry)                                  | When and how many times a job can be auto-retried in case of a failure.                                                                                                             |
-| [`rules`](#rules)                                  | List of conditions to evaluate and determine selected attributes of a job, and whether or not it's created. May not be used alongside `only`/`except`.                              |
+| [`rules`](#rules)                                  | List of conditions to evaluate and determine selected attributes of a job, and whether or not it's created.                                                                         |
 | [`services`](#services)                            | Use Docker services images. Also available: `services:name`, `services:alias`, `services:entrypoint`, and `services:command`.                                                       |
 | [`stage`](#stage)                                  | Defines a job stage (default: `test`).                                                                                                                                              |
 | [`tags`](#tags)                                    | List of tags that are used to select a runner.                                                                                                                                      |
@@ -57,8 +57,8 @@ The keywords available for jobs are:
 
 ### 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**:
+Each job must have a unique name, but there are a few reserved `keywords` that
+can't be used as job names:
 
 - `image`
 - `services`
@@ -416,14 +416,14 @@ include:
   - local: '/templates/.gitlab-ci-template.yml'
 ```
 
-Local includes can be used as a replacement for symbolic links that are not followed.
-
 This can be defined as a short local include:
 
 ```yaml
 include: '.gitlab-ci-production.yml'
 ```
 
+Use local includes instead of symbolic links.
+
 #### `include:file`
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53903) in GitLab 11.7.
@@ -477,7 +477,7 @@ include:
 
 #### `include:remote`
 
-`include:remote` can be used to include a file from a different location,
+Use `include:remote` to include a file from a different location,
 using HTTP/HTTPS, referenced by the full URL. The remote file must be
 publicly accessible by a GET request, because authentication schemas
 in the remote URL are not supported. For example:
@@ -494,7 +494,7 @@ so you can only `include` public projects or templates.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53445) in GitLab 11.7.
 
-`include:template` can be used to include `.gitlab-ci.yml` templates that are
+Use `include:template` to include `.gitlab-ci.yml` templates that are
 [shipped with GitLab](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates).
 
 For example:
@@ -653,7 +653,7 @@ job:
 
 #### `before_script`
 
-`before_script` is used to define an array of commands that should run before each job,
+Use `before_script` to define an array of commands that should run before each job,
 but after [artifacts](#artifacts) are restored.
 
 Scripts specified in `before_script` are concatenated with any scripts specified
@@ -681,7 +681,7 @@ You can use [YAML anchors with `before_script`](#yaml-anchors-for-scripts).
 
 #### `after_script`
 
-`after_script` is used to define an array of commands that run after each job,
+Use `after_script` to define an array of commands that run after each job,
 including failed jobs.
 
 If a job times out or is cancelled, the `after_script` commands are not executed.
@@ -955,12 +955,10 @@ rspec:
 
 Note that in the example above:
 
-- `variables` sections have been merged but that `URL: "http://my-url.internal"`
-has been overwritten by `URL: "http://docker-url.internal"`.
-- `tags: ['production']` has been overwritten by `tags: ['docker']`.
-- `script` has not been merged but rather `script: ['echo "Hello world!"']` has
-  been overwritten by `script: ['rake rspec']`. Arrays can be
-  merged using [YAML anchors](#anchors).
+- The `variables` sections merge, but `URL: "http://docker-url.internal"` overwrites `URL: "http://my-url.internal"`.
+- `tags: ['docker']` overwrites `tags: ['production']`.
+- `script` does not merge, but `script: ['rake rspec']` overwrites
+  `script: ['echo "Hello world!"']`. You can use [YAML anchors](#anchors) to merge arrays.
 
 #### Using `extends` and `include` together
 
@@ -991,15 +989,15 @@ the `.template` job, and uses the `alpine` Docker image as defined in the local
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3.
 
-The `rules` keyword can be used to include or exclude jobs in pipelines.
+Use the `rules` keyword to include or exclude jobs in pipelines.
 
 Rules are evaluated *in order* until the first match. When matched, the job
 is either included or excluded from the pipeline, depending on the configuration.
 If included, the job also has [certain attributes](#rules-attributes)
 added to it.
 
-`rules` replaces [`only/except`](#onlyexcept-basic) and can't be used in conjunction with it.
-If you attempt to use both keywords in the same job, the linter returns a
+`rules` replaces [`only/except`](#onlyexcept-basic) and they can't be used together
+in the same job. If you configure one job to use both keywords, the linter returns a
 `key may not be used with rules` error.
 
 #### Rules attributes
@@ -1376,7 +1374,7 @@ docker build:
         - $DOCKERFILES_DIR/*
 ```
 
-The `$` character can be used for both variables and paths. For example, if the
+You can use The `$` character for both variables and paths. For example, if the
 `$DOCKERFILES_DIR` variable exists, its value is used. If it does not exist, the
 `$` is interpreted as being part of a path.
 
@@ -1606,7 +1604,7 @@ job:
     - schedules
 ```
 
-The repository path can be used to have jobs executed only for the parent
+Use the repository path to have jobs executed only for the parent
 repository and not forks:
 
 ```yaml
@@ -1624,17 +1622,13 @@ except `master` and those with names prefixed with `release/`.
 If a job does not have an `only` rule, `only: ['branches', 'tags']` is set by
 default. If it does not have an `except` rule, it's empty.
 
-For example,
+For example, `job1` and `job2` are essentially the same:
 
 ```yaml
-job:
+job1:
   script: echo 'test'
-```
 
-is translated to:
-
-```yaml
-job:
+job2:
   script: echo 'test'
   only: ['branches', 'tags']
 ```
@@ -1704,7 +1698,7 @@ the pipeline if the following is true:
 
 In the example below, the `test` job is `only` created when **all** of the following are true:
 
-- The pipeline has been [scheduled](../pipelines/schedules.md) **or** runs for `master`.
+- The pipeline is [scheduled](../pipelines/schedules.md) **or** runs for `master`.
 - The `variables` keyword matches.
 - The `kubernetes` service is active on the project.
 
@@ -2320,10 +2314,10 @@ test_job_2:
 
 ### `when`
 
-`when` is used to implement jobs that are run in case of failure or despite the
+Use `when` to implement jobs that run in case of failure or despite the
 failure.
 
-`when` can be set to one of the following values:
+The valid values of `when` are:
 
 1. `on_success` (default) - Execute job only when all jobs in earlier stages succeed,
     or are considered successful because they have `allow_failure: true`.
@@ -2470,13 +2464,13 @@ provided. `start_in` must be less than or equal to one week. Examples of valid v
 - `1 day`
 - `1 week`
 
-When there is a delayed job in a stage, the pipeline doesn't progress until the delayed job has finished.
-This keyword can also be used for inserting delays between different stages.
+When a stage includes a delayed job, the pipeline doesn't progress until the delayed job finishes.
+You can use this keyword to insert delays between different stages.
 
-The timer of a delayed job starts immediately after the previous stage has completed.
-Similar to other types of jobs, a delayed job's timer doesn't start unless the previous stage passed.
+The timer of a delayed job starts immediately after the previous stage completes.
+Similar to other types of jobs, a delayed job's timer doesn't start unless the previous stage passes.
 
-The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage has completed:
+The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage completes:
 
 ```yaml
 timed rollout 10%:
@@ -2486,7 +2480,7 @@ timed rollout 10%:
   start_in: 30 minutes
 ```
 
-You can stop the active timer of a delayed job by clicking the **{time-out}** (**Unschedule**) button.
+To stop the active timer of a delayed job, click the **{time-out}** (**Unschedule**) button.
 This job can no longer be scheduled to run automatically. You can, however, execute the job manually.
 
 To start a delayed job immediately, click the **Play** button.
@@ -2583,7 +2577,7 @@ Read the `environment:action` section for an example.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22191) in GitLab 8.13.
 
-The `action` keyword can be used to specify jobs that prepare, start, or stop environments.
+Use the `action` keyword to specify jobs that prepare, start, or stop environments.
 
 | **Value** | **Description**                                                                                                                                               |
 |-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -2669,7 +2663,7 @@ For more information, see
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6.
 
-The `kubernetes` block is used to configure deployments to a
+Use the `kubernetes` keyword to configure deployments to a
 [Kubernetes cluster](../../user/project/clusters/index.md) that is associated with your project.
 
 For example:
@@ -2725,10 +2719,10 @@ as Review Apps. You can see an example that uses Review Apps at
 
 ### `cache`
 
-`cache` is used to specify a list of files and directories that should be
-cached between jobs. You can only use paths that are in the local working copy.
+Use the `cache` keyword to specify a list of files and directories to
+cache between jobs. You can only use paths that are in the local working copy.
 
-If `cache` is defined outside the scope of jobs, it means it's set
+If `cache` is defined outside the scope of jobs, it's set
 globally and all jobs use that configuration.
 
 Caching is shared between pipelines and jobs. Caches are restored before [artifacts](#artifacts).
@@ -2740,7 +2734,7 @@ Read how caching works and find out some good practices in the
 
 Use the `paths` directive to choose which files or directories to cache. Paths
 are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly link outside it.
-Wildcards can be used that follow the [glob](https://en.wikipedia.org/wiki/Glob_(programming))
+You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming))
 patterns and:
 
 - In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) and later,
@@ -2851,7 +2845,7 @@ runs.
 
 When you include `cache:key:files`, you must also list the project files that are used to generate the key, up to a maximum of two files.
 The cache `key` is a SHA checksum computed from the most recent commits (up to two, if two files are listed)
-that changed the given files. If neither file was changed in any commits,
+that changed the given files. If neither file is changed in any commits,
 the fallback key is `default`.
 
 ```yaml
@@ -2878,7 +2872,7 @@ use the new cache, instead of rebuilding the dependencies.
 When you want to combine a prefix with the SHA computed for `cache:key:files`,
 use the `prefix` keyword with `key:files`.
 For example, if you add a `prefix` of `test`, the resulting key is: `test-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5`.
-If neither file was changed in any commits, the prefix is added to `default`, so the
+If neither file is changed in any commits, the prefix is added to `default`, so the
 key in the example would be `test-default`.
 
 Like `cache:key`, `prefix` can use any of the [predefined variables](../variables/README.md),
@@ -2990,8 +2984,8 @@ rspec:
     - bundle exec rspec ...
 ```
 
-The `pull` policy speeds up job execution and reduces load on the cache server. It
-can be used when you have many jobs that use caches executing in parallel.
+Use the `pull` policy when you have many jobs executing in parallel that use caches. This
+policy speeds up job execution and reduces load on the cache server.
 
 If you have a job that unconditionally recreates the cache without
 referring to its previous contents, you can skip the download step.
@@ -2999,7 +2993,7 @@ To do so, add `policy: push` to the job.
 
 ### `artifacts`
 
-`artifacts` is used to specify a list of files and directories that are
+Use the `artifacts` keyword to specify a list of files and directories that are
 attached to the job when it [succeeds, fails, or always](#artifactswhen).
 
 The artifacts are sent to GitLab after the job finishes. They are
@@ -3014,7 +3008,7 @@ artifacts are restored after [caches](#cache).
 #### `artifacts:paths`
 
 Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly
-link outside it. Wildcards can be used that follow the [glob](https://en.wikipedia.org/wiki/Glob_(programming))
+link outside it. You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming))
 patterns and:
 
 - In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) and later,
@@ -3080,7 +3074,7 @@ job:
 > - It's enabled on GitLab.com.
 > - It's recommended for production use.
 
-`artifacts:public` is used to determine whether the job artifacts should be
+Use `artifacts:public` to determine whether the job artifacts should be
 publicly available.
 
 The default for `artifacts:public` is `true` which means that the artifacts in
@@ -3108,9 +3102,9 @@ artifacts:
 archive.
 
 Similar to [`artifacts:paths`](#artifactspaths), `exclude` paths are relative
-to the project directory. Wildcards can be used that follow the
-[glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns and
-[`filepath.Match`](https://golang.org/pkg/path/filepath/#Match).
+to the project directory. You can use Wildcards that use
+[glob](https://en.wikipedia.org/wiki/Glob_(programming)) or
+[`filepath.Match`](https://golang.org/pkg/path/filepath/#Match) patterns.
 
 For example, to store all files in `binaries/`, but not `*.o` files located in
 subdirectories of `binaries/`:
@@ -3130,7 +3124,7 @@ Files matched by [`artifacts:untracked`](#artifactsuntracked) can be excluded us
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15018) in GitLab 12.5.
 
-The `expose_as` keyword can be used to expose [job artifacts](../pipelines/job_artifacts.md)
+Use the `expose_as` keyword to expose [job artifacts](../pipelines/job_artifacts.md)
 in the [merge request](../../user/project/merge_requests/index.md) UI.
 
 For example, to match a single file:
@@ -3247,8 +3241,8 @@ job:
 
 #### `artifacts:untracked`
 
-`artifacts:untracked` is used to add all Git untracked files as artifacts (along
-to the paths defined in `artifacts:paths`). `artifacts:untracked` ignores configuration
+Use `artifacts:untracked` to add all Git untracked files as artifacts (along
+with the paths defined in `artifacts:paths`). `artifacts:untracked` ignores configuration
 in the repository's `.gitignore` file.
 
 Send all Git untracked files:
@@ -3278,7 +3272,7 @@ artifacts:
 
 #### `artifacts:when`
 
-`artifacts:when` is used to upload artifacts on job failure or despite the
+Use `artifacts:when` to upload artifacts on job failure or despite the
 failure.
 
 `artifacts:when` can be set to one of the following values:
@@ -3342,8 +3336,8 @@ in GitLab 13.4. In [GitLab 13.8 and later](https://gitlab.com/gitlab-org/gitlab/
 
 #### `artifacts:reports`
 
-The [`artifacts:reports` keyword](../pipelines/job_artifacts.md#artifactsreports)
-is used for collecting test reports, code quality reports, and security reports from jobs.
+Use [`artifacts:reports`](../pipelines/job_artifacts.md#artifactsreports)
+to collect test reports, code quality reports, and security reports from jobs.
 It also exposes these reports in the GitLab UI (merge requests, pipeline views, and security dashboards).
 
 These are the available report types:
@@ -3380,7 +3374,7 @@ An error occurs if you define jobs from the current or an upcoming stage.
 To prevent a job from downloading artifacts, define an empty array.
 
 When you use `dependencies`, the status of the previous job is not considered.
-If a job fails or it's a manual job that was not run, no error occurs.
+If a job fails or it's a manual job that isn't triggered, no error occurs.
 
 The following example defines two jobs with artifacts: `build:osx` and
 `build:linux`. When the `test:osx` is executed, the artifacts from `build:osx`
@@ -3426,7 +3420,7 @@ deploy:
 
 > Introduced in GitLab 10.3.
 
-If the artifacts of the job that is set as a dependency have been
+If the artifacts of the job that is set as a dependency are
 [expired](#artifactsexpire_in) or
 [erased](../pipelines/job_artifacts.md#erasing-artifacts), then
 the dependent job fails.
@@ -3531,15 +3525,15 @@ Possible values for `when` are:
 - `script_failure`: Retry when the script failed.
 - `api_failure`: Retry on API failure.
 - `stuck_or_timeout_failure`: Retry when the job got stuck or timed out.
-- `runner_system_failure`: Retry if there was a runner system failure (for example, job setup failed).
-- `missing_dependency_failure`: Retry if a dependency was missing.
-- `runner_unsupported`: Retry if the runner was unsupported.
+- `runner_system_failure`: Retry if there is a runner system failure (for example, job setup failed).
+- `missing_dependency_failure`: Retry if a dependency is missing.
+- `runner_unsupported`: Retry if the runner is unsupported.
 - `stale_schedule`: Retry if a delayed job could not be executed.
 - `job_execution_timeout`: Retry if the script exceeded the maximum execution time set for the job.
 - `archived_failure`: Retry if the job is archived and can't be run.
 - `unmet_prerequisites`: Retry if the job failed to complete prerequisite tasks.
 - `scheduler_failure`: Retry if the scheduler failed to assign the job to a runner.
-- `data_integrity_failure`: Retry if there was a structural integrity problem detected.
+- `data_integrity_failure`: Retry if there is a structural integrity problem detected.
 
 You can specify the number of [retry attempts for certain stages of job execution](../runners/README.md#job-stages-attempts) using variables.
 
@@ -3848,7 +3842,7 @@ The trigger token is different than the [`trigger`](#trigger) keyword.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3.
 
-`interruptible` is used to indicate that a running job should be canceled if made redundant by a newer pipeline run.
+Use `interruptible` to indicate that a running job should be canceled if made redundant by a newer pipeline run.
 Defaults to `false` (uninterruptible). Jobs that have not started yet (pending) are considered interruptible
 and safe to be cancelled.
 This value is used only if the [automatic cancellation of redundant pipelines feature](../pipelines/settings.md#auto-cancel-pending-pipelines)
@@ -3901,7 +3895,7 @@ When an uninterruptible job is running, the pipeline cannot be canceled, regardl
 Sometimes running multiple jobs or pipelines at the same time in an environment
 can lead to errors during the deployment.
 
-To avoid these errors, the `resource_group` attribute can be used to ensure that
+To avoid these errors, use the `resource_group` attribute to make sure that
 the runner doesn't run certain jobs simultaneously. Resource groups behave similar
 to semaphores in other programming languages.
 
@@ -3960,7 +3954,7 @@ image: registry.gitlab.com/gitlab-org/release-cli:latest
 #### Script
 
 All jobs except [trigger](#trigger) jobs must have the `script` keyword. A `release`
-job can use the output from script commands, but a placeholder script can be used if
+job can use the output from script commands, but you can use a placeholder script if
 the script is not needed:
 
 ```yaml
@@ -4063,7 +4057,7 @@ released_at: '2021-03-15T08:00:00Z'
 
 Combining the individual examples given above for `release` results in the following
 code snippets. There are two options, depending on how you generate the
-tags. These options cannot be used together, so choose one:
+tags. You can't use these options together, so choose one:
 
 - To create a release when you push a Git tag, or when you add a Git tag
   in the UI by going to **Repository > Tags**:
@@ -4203,8 +4197,8 @@ job:
 
 ### `pages`
 
-`pages` is a special job that is used to upload static content to GitLab that
-can be used to serve your website. It has a special syntax, so the two
+`pages` is a special job that uploads static content to GitLab that
+is then published as a website. It has a special syntax, so the two
 requirements below must be met:
 
 - Any static content must be placed under a `public/` directory.
@@ -4274,7 +4268,7 @@ meaning it applies to all jobs. If you define a variable in a job, it's availabl
 to that job only.
 
 If a variable of the same name is defined globally and for a specific job, the
-[job-specific variable is used](../variables/README.md#priority-of-environment-variables).
+[job-specific variable overrides the global variable](../variables/README.md#priority-of-environment-variables).
 
 All YAML-defined variables are also set to any linked
 [Docker service containers](../docker/using_docker_images.md#what-is-a-service).
@@ -4305,8 +4299,9 @@ of the code in the `.gitlab-ci.yml` file.
 Read more about the various [YAML features](https://learnxinyminutes.com/docs/yaml/).
 
 In most cases, the [`extends` keyword](#extends) is more user friendly and should
-be used over these special YAML features. YAML anchors may still
-need to be used to merge arrays.
+be used over these special YAML features.
+
+You can use YAML anchors to merge YAML arrays.
 
 ### Anchors
 
@@ -4442,7 +4437,7 @@ test:mysql:
 ```
 
 You can see that the hidden jobs are conveniently used as templates, and
-`tags: [dev]` has been overwritten by `tags: [postgres]`.
+`tags: [postgres]` overwrites `tags: [dev]`.
 
 #### YAML anchors for scripts
 
@@ -4481,8 +4476,8 @@ job2:
 
 #### YAML anchors for variables
 
-[YAML anchors](#anchors) can be used with `variables`, to repeat assignment
-of variables across multiple jobs. Use can also use YAML anchors when a job
+Use [YAML anchors](#anchors) with `variables` to repeat assignment
+of variables across multiple jobs. You can also use YAML anchors when a job
 requires a specific `variables` block that would otherwise override the global variables.
 
 In the example below, we override the `GIT_STRATEGY` variable without affecting