Merge branch 'docs-update-workflow-keyword' into 'master'

Update workflow keyword to new reference style

See merge request gitlab-org/gitlab!74051

doc/ci/jobs/job_control.md

@@ -179,7 +179,7 @@ job:
 ```
 
 You should not include both push and merge request pipelines in the same job without
-[`workflow:rules` that prevent duplicate pipelines](../yaml/index.md#switch-between-branch-pipelines-and-merge-request-pipelines):
+[`workflow:rules` that prevent duplicate pipelines](../yaml/workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines):
 
 ```yaml
 job:

doc/ci/pipelines/merge_request_pipelines.md

@@ -45,7 +45,7 @@ To do this, you can use [`rules`](#use-rules-to-run-pipelines-for-merge-requests
 ### Use `rules` to run pipelines for merge requests
 
 GitLab recommends that you use the `rules` keyword, which is available in
-[`workflow:rules` templates](../yaml/index.md#workflowrules-templates).
+[`workflow:rules` templates](../yaml/workflow.md#workflowrules-templates).
 
 ### Use `only` or `except` to run pipelines for merge requests
 
@@ -199,7 +199,7 @@ If you are seeing two pipelines when using `only/except`, please see the caveats
 related to using `only/except` above (or, consider moving to `rules`).
 
 In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201845),
-you can add `workflow:rules` to [switch from branch pipelines to merge request pipelines](../yaml/index.md#switch-between-branch-pipelines-and-merge-request-pipelines).
+you can add `workflow:rules` to [switch from branch pipelines to merge request pipelines](../yaml/workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines).
 After a merge request is open on the branch, the pipeline switches to a merge request pipeline.
 
 ### Two pipelines created when pushing an invalid CI configuration file

doc/ci/yaml/index.md

@@ -171,14 +171,21 @@ start. Jobs in the current stage are not stopped and continue to run.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) in GitLab 12.5
 
-Use `workflow:` to determine whether or not a pipeline is created.
-Define this keyword at the top level, with a single `rules:` keyword that
-is similar to [`rules:` defined in jobs](#rules).
+Use [`workflow`](workflow.md) to control pipeline behavior.
 
-You can use the [`workflow:rules` templates](#workflowrules-templates) to import
-a preconfigured `workflow: rules` entry.
+**Related topics**:
+
+- [`workflow: rules` examples](workflow.md#workflow-rules-examples)
+- [Switch between branch pipelines and merge request pipelines](workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines)
+
+#### `workflow:rules`
 
-`workflow: rules` accepts some of the same keywords as [`rules`](#rules):
+The `rules` keyword in `workflow` is similar to [`rules:` defined in jobs](#rules),
+but controls whether or not a whole pipeline is created.
+
+When no rules evaluate to true, the pipeline does not run.
+
+**Possible inputs**: You can use some of the same keywords as job-level [`rules`](#rules):
 
 - [`rules: if`](#rulesif).
 - [`rules: changes`](#ruleschanges).
@@ -186,63 +193,54 @@ a preconfigured `workflow: rules` entry.
 - [`when`](#when), can only be `always` or `never` when used with `workflow`.
 - [`variables`](#workflowrulesvariables).
 
-When no rules evaluate to true, the pipeline does not run.
-
-Some example `if` clauses for `workflow: rules`:
-
-| Example rules                                        | Details                                                   |
-|------------------------------------------------------|-----------------------------------------------------------|
-| `if: '$CI_PIPELINE_SOURCE == "merge_request_event"'` | Control when merge request pipelines run.                 |
-| `if: '$CI_PIPELINE_SOURCE == "push"'`                | Control when both branch pipelines and tag pipelines run. |
-| `if: $CI_COMMIT_TAG`                                 | Control when tag pipelines run.                           |
-| `if: $CI_COMMIT_BRANCH`                              | Control when branch pipelines run.                        |
-
-See the [common `if` clauses for `rules`](../jobs/job_control.md#common-if-clauses-for-rules) for more examples.
-
-In the following example, pipelines run for all `push` events (changes to
-branches and new tags). Pipelines for push events with `-draft` in the commit message
-don't run, because they are set to `when: never`. Pipelines for schedules or merge requests
-don't run either, because no rules evaluate to true for them:
+**Example of `workflow:rules`:**
 
 ```yaml
 workflow:
   rules:
     - if: $CI_COMMIT_MESSAGE =~ /-draft$/
       when: never
-    - if: '$CI_PIPELINE_SOURCE == "push"'
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 ```
 
-This example has strict rules, and pipelines do **not** run in any other case.
+In this example, pipelines run if the commit message does not have `-drafts` in it
+and the pipeline is for either:
 
-Alternatively, all of the rules can be `when: never`, with a final
-`when: always` rule. Pipelines that match the `when: never` rules do not run.
-All other pipeline types run:
+- A merge request
+- The default branch.
 
-```yaml
-workflow:
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "schedule"'
-      when: never
-    - if: '$CI_PIPELINE_SOURCE == "push"'
-      when: never
-    - when: always
-```
+**Additional details**:
+
+- If your rules match both branch pipelines (other than the default branch) and merge request pipelines,
+  [duplicate pipelines](../jobs/job_control.md#avoid-duplicate-pipelines) can occur.
 
-This example prevents pipelines for schedules or `push` (branches and tags) pipelines.
-The final `when: always` rule runs all other pipeline types, **including** merge
-request pipelines.
+**Related topics**:
 
-If your rules match both branch pipelines and merge request pipelines,
-[duplicate pipelines](../jobs/job_control.md#avoid-duplicate-pipelines) can occur.
+- You can use the [`workflow:rules` templates](workflow.md#workflowrules-templates) to import
+  a preconfigured `workflow: rules` entry.
+- [Common `if` clauses for `workflow:rules`](workflow.md#common-if-clauses-for-workflowrules).
 
 #### `workflow:rules:variables`
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294232) in GitLab 13.11.
 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/300997) in GitLab 14.1.
 
-You can use [`variables`](#variables) in `workflow:rules:` to define variables for specific pipeline conditions.
+You can use [`variables`](#variables) in `workflow:rules:` to define variables for
+specific pipeline conditions.
 
-For example:
+When the condition matches, the variable is created and can be used by all jobs
+in the pipeline. If the variable is already defined at the global level, the `workflow`
+variable takes precedence and overrides the global variable.
+
+**Keyword type**: Global keyword.
+
+**Possible inputs**: Variable name and value pairs:
+
+- The name can use only numbers, letters, and underscores (`_`).
+- The value must be a string.
+
+**Example of `workflow:rules:variables`:**
 
 ```yaml
 variables:
@@ -291,94 +289,6 @@ When the branch is something else:
 - job1's `DEPLOY_VARIABLE` is `job1-default-deploy`.
 - job2's `DEPLOY_VARIABLE` is `default-deploy`.
 
-#### `workflow:rules` templates
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217732) in GitLab 13.0.
-
-GitLab provides templates that set up `workflow: rules`
-for common scenarios. These templates help prevent duplicate pipelines.
-
-The [`Branch-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/Branch-Pipelines.gitlab-ci.yml)
-makes your pipelines run for branches and tags.
-
-Branch pipeline status is displayed in merge requests that use the branch
-as a source. However, this pipeline type does not support any features offered by
-[merge request pipelines](../pipelines/merge_request_pipelines.md), like
-[pipelines for merged results](../pipelines/pipelines_for_merged_results.md)
-or [merge trains](../pipelines/merge_trains.md).
-This template intentionally avoids those features.
-
-To [include](#include) it:
-
-```yaml
-include:
-  - template: 'Workflows/Branch-Pipelines.gitlab-ci.yml'
-```
-
-The [`MergeRequest-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/MergeRequest-Pipelines.gitlab-ci.yml)
-makes your pipelines run for the default branch, tags, and
-all types of merge request pipelines. Use this template if you use any of the
-the [pipelines for merge requests features](../pipelines/merge_request_pipelines.md).
-
-To [include](#include) it:
-
-```yaml
-include:
-  - template: 'Workflows/MergeRequest-Pipelines.gitlab-ci.yml'
-```
-
-#### Switch between branch pipelines and merge request pipelines
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201845) in GitLab 13.8.
-
-To make the pipeline switch from branch pipelines to merge request pipelines after
-a merge request is created, add a `workflow: rules` section to your `.gitlab-ci.yml` file.
-
-If you use both pipeline types at the same time, [duplicate pipelines](../jobs/job_control.md#avoid-duplicate-pipelines)
-might run at the same time. To prevent duplicate pipelines, use the
-[`CI_OPEN_MERGE_REQUESTS` variable](../variables/predefined_variables.md).
-
-The following example is for a project that runs branch and merge request pipelines only,
-but does not run pipelines for any other case. It runs:
-
-- Branch pipelines when a merge request is not open for the branch.
-- Merge request pipelines when a merge request is open for the branch.
-
-```yaml
-workflow:
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
-      when: never
-    - if: '$CI_COMMIT_BRANCH'
-```
-
-If the pipeline is triggered by:
-
-- A merge request, run a merge request pipeline. For example, a merge request pipeline
-  can be triggered by a push to a branch with an associated open merge request.
-- A change to a branch, but a merge request is open for that branch, do not run a branch pipeline.
-- A change to a branch, but without any open merge requests, run a branch pipeline.
-
-You can also add a rule to an existing `workflow` section to switch from branch pipelines
-to merge request pipelines when a merge request is created.
-
-Add this rule to the top of the `workflow` section, followed by the other rules that
-were already present:
-
-```yaml
-workflow:
-  rules:
-    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"
-      when: never
-    - ...                # Previously defined workflow rules here
-```
-
-[Triggered pipelines](../triggers/index.md) that run on a branch have a `$CI_COMMIT_BRANCH`
-set and could be blocked by a similar rule. Triggered pipelines have a pipeline source
-of `trigger` or `pipeline`, so `&& $CI_PIPELINE_SOURCE == "push"` ensures the rule
-does not block triggered pipelines.
-
 ### `include`
 
 > [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Free in 11.4.

doc/ci/yaml/script.md

@@ -2,7 +2,6 @@
 stage: Verify
 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
-type: reference
 ---
 
 # GitLab CI/CD script syntax **(FREE)**

doc/ci/yaml/workflow.md

+---
+stage: Verify
+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
+---
+
+# GitLab CI/CD `workflow` keyword
+
+Use the [`workflow`](index.md#workflow) keyword to control when pipelines are created.
+
+The `workflow` keyword is evaluated before jobs. For example, if a job is configured to run
+for tags, but the workflow prevents tag pipelines, the job never runs.
+
+## Common `if` clauses for `workflow:rules`
+
+Some example `if` clauses for `workflow: rules`:
+
+| Example rules                                        | Details                                                   |
+|------------------------------------------------------|-----------------------------------------------------------|
+| `if: '$CI_PIPELINE_SOURCE == "merge_request_event"'` | Control when merge request pipelines run.                 |
+| `if: '$CI_PIPELINE_SOURCE == "push"'`                | Control when both branch pipelines and tag pipelines run. |
+| `if: $CI_COMMIT_TAG`                                 | Control when tag pipelines run.                           |
+| `if: $CI_COMMIT_BRANCH`                              | Control when branch pipelines run.                        |
+
+See the [common `if` clauses for `rules`](../jobs/job_control.md#common-if-clauses-for-rules) for more examples.
+
+## `workflow: rules` examples
+
+In the following example:
+
+- Pipelines run for all `push` events (changes to branches and new tags).
+- Pipelines for push events with `-draft` in the commit message don't run, because
+  they are set to `when: never`.
+- Pipelines for schedules or merge requests don't run either, because no rules evaluate to true for them.
+
+```yaml
+workflow:
+  rules:
+    - if: $CI_COMMIT_MESSAGE =~ /-draft$/
+      when: never
+    - if: '$CI_PIPELINE_SOURCE == "push"'
+```
+
+This example has strict rules, and pipelines do **not** run in any other case.
+
+Alternatively, all of the rules can be `when: never`, with a final
+`when: always` rule. Pipelines that match the `when: never` rules do not run.
+All other pipeline types run. For example:
+
+```yaml
+workflow:
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "schedule"'
+      when: never
+    - if: '$CI_PIPELINE_SOURCE == "push"'
+      when: never
+    - when: always
+```
+
+This example prevents pipelines for schedules or `push` (branches and tags) pipelines.
+The final `when: always` rule runs all other pipeline types, **including** merge
+request pipelines.
+
+## Switch between branch pipelines and merge request pipelines
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201845) in GitLab 13.8.
+
+To make the pipeline switch from branch pipelines to merge request pipelines after
+a merge request is created, add a `workflow: rules` section to your `.gitlab-ci.yml` file.
+
+If you use both pipeline types at the same time, [duplicate pipelines](../jobs/job_control.md#avoid-duplicate-pipelines)
+might run at the same time. To prevent duplicate pipelines, use the
+[`CI_OPEN_MERGE_REQUESTS` variable](../variables/predefined_variables.md).
+
+The following example is for a project that runs branch and merge request pipelines only,
+but does not run pipelines for any other case. It runs:
+
+- Branch pipelines when a merge request is not open for the branch.
+- Merge request pipelines when a merge request is open for the branch.
+
+```yaml
+workflow:
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
+      when: never
+    - if: '$CI_COMMIT_BRANCH'
+```
+
+If the pipeline is triggered by:
+
+- A merge request, run a merge request pipeline. For example, a merge request pipeline
+  can be triggered by a push to a branch with an associated open merge request.
+- A change to a branch, but a merge request is open for that branch, do not run a branch pipeline.
+- A change to a branch, but without any open merge requests, run a branch pipeline.
+
+You can also add a rule to an existing `workflow` section to switch from branch pipelines
+to merge request pipelines when a merge request is created.
+
+Add this rule to the top of the `workflow` section, followed by the other rules that
+were already present:
+
+```yaml
+workflow:
+  rules:
+    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"
+      when: never
+    - ...                # Previously defined workflow rules here
+```
+
+[Triggered pipelines](../triggers/index.md) that run on a branch have a `$CI_COMMIT_BRANCH`
+set and could be blocked by a similar rule. Triggered pipelines have a pipeline source
+of `trigger` or `pipeline`, so `&& $CI_PIPELINE_SOURCE == "push"` ensures the rule
+does not block triggered pipelines.
+
+## `workflow:rules` templates
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217732) in GitLab 13.0.
+
+GitLab provides templates that set up `workflow: rules`
+for common scenarios. These templates help prevent duplicate pipelines.
+
+The [`Branch-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/Branch-Pipelines.gitlab-ci.yml)
+makes your pipelines run for branches and tags.
+
+Branch pipeline status is displayed in merge requests that use the branch
+as a source. However, this pipeline type does not support any features offered by
+[merge request pipelines](../pipelines/merge_request_pipelines.md), like
+[pipelines for merged results](../pipelines/pipelines_for_merged_results.md)
+or [merge trains](../pipelines/merge_trains.md).
+This template intentionally avoids those features.
+
+To [include](index.md#include) it:
+
+```yaml
+include:
+  - template: 'Workflows/Branch-Pipelines.gitlab-ci.yml'
+```
+
+The [`MergeRequest-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/MergeRequest-Pipelines.gitlab-ci.yml)
+makes your pipelines run for the default branch, tags, and
+all types of merge request pipelines. Use this template if you use any of the
+the [pipelines for merge requests features](../pipelines/merge_request_pipelines.md).
+
+To [include](index.md#include) it:
+
+```yaml
+include:
+  - template: 'Workflows/MergeRequest-Pipelines.gitlab-ci.yml'
+```