Merge branch 'docs-control-jobs-variable-table' into 'master'

Add table for variables in job control page

See merge request gitlab-org/gitlab!61765

doc/ci/jobs/job_control.md

@@ -63,7 +63,7 @@ except `main` and branches that start with `release/`.
 
 ### `only: variables` / `except: variables` examples
 
-You can use `except:variables` to exclude jobs based on a commit message:
+You can use [`except:variables`](../yaml/README.md#onlyvariables--exceptvariables) to exclude jobs based on a commit message:
 
 ```yaml
 end-to-end:
@@ -223,6 +223,48 @@ test:
       - "README.md"
 ```
 
+## Use predefined CI/CD variables to run jobs only in specific pipeline types
+
+You can use [predefined CI/CD variables](../variables/predefined_variables.md) to choose
+which pipeline types jobs run in, with:
+
+- [`rules`](../yaml/README.md#rules)
+- [`only:variables`](../yaml/README.md#onlyvariables--exceptvariables)
+- [`except:variables`](../yaml/README.md#onlyvariables--exceptvariables)
+
+The following table lists some of the variables that you can use, and the pipeline
+types the variables can control for:
+
+- Branch pipelines that run for Git `push` events to a branch, like new commits or tags.
+- Tag pipelines that run only when a new Git tag is pushed to a branch.
+- [Merge request pipelines](../merge_request_pipelines/index.md) that run for changes
+  to a merge request, like new commits or selecting the **Run pipeline** button
+  in a merge request's pipelines tab.
+- [Scheduled pipelines](../pipelines/schedules.md).
+
+| Variables                                  | Branch | Tag | Merge request | Scheduled |
+|--------------------------------------------|--------|-----|---------------|-----------|
+| `CI_COMMIT_BRANCH`                         | Yes    |     |               | Yes       |
+| `CI_COMMIT_TAG`                            |        | Yes |               | Yes, if the scheduled pipeline is configured to run on a tag. |
+| `CI_PIPELINE_SOURCE = push`                | Yes    | Yes |               |           |
+| `CI_PIPELINE_SOURCE = scheduled`           |        |     |               | Yes       |
+| `CI_PIPELINE_SOURCE = merge_request_event` |        |     | Yes           |           |
+| `CI_MERGE_REQUEST_IID`                     |        |     | Yes           |           |
+
+For example, to configure a job to run for merge request pipelines and scheduled pipelines,
+but not branch or tag pipelines:
+
+```yaml
+job1:
+  script:
+    - echo
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_PIPELINE_SOURCE == "scheduled"
+    - if: $CI_PIPELINE_SOURCE == "push"
+      when: never
+```
+
 ## Regular expressions
 
 The `@` symbol denotes the beginning of a ref's repository path.

doc/ci/yaml/README.md

@@ -36,14 +36,14 @@ The keywords available for jobs are:
 | [`coverage`](#coverage)             | Code coverage settings for a given job. |
 | [`dependencies`](#dependencies)     | Restrict which artifacts are passed to a specific job by providing a list of jobs to fetch artifacts from. |
 | [`environment`](#environment)       | Name of an environment to which the job deploys. |
-| [`except`](#only--except)             | Control when jobs are not created. |
+| [`except`](#only--except)           | Control when jobs are not created. |
 | [`extends`](#extends)               | Configuration entries that this job inherits from. |
 | [`image`](#image)                   | Use Docker images. |
 | [`include`](#include)               | Include external YAML files. |
 | [`inherit`](#inherit)               | Select which global defaults all jobs inherit. |
 | [`interruptible`](#interruptible)   | Defines if a job can be canceled when made redundant by a newer run. |
 | [`needs`](#needs)                   | Execute jobs earlier than the stage ordering. |
-| [`only`](#only--except)               | Control when jobs are created. |
+| [`only`](#only--except)             | Control when jobs are created. |
 | [`pages`](#pages)                   | Upload the result of a job to use with GitLab Pages. |
 | [`parallel`](#parallel)             | How many instances of a job should be run in parallel. |
 | [`release`](#release)               | Instructs the runner to generate a [release](../../user/project/releases/index.md) object. |
@@ -1615,7 +1615,7 @@ Four keywords can be used with `only` and `except`:
 - [`changes`](#onlychanges--exceptchanges)
 - [`kubernetes`](#onlykubernetes--exceptkubernetes)
 
-See [control jobs with `only` and `except`](../jobs/job_control.md#specify-when-jobs-run-with-only-and-except)
+See [specify when jobs run with `only` and `except`](../jobs/job_control.md#specify-when-jobs-run-with-only-and-except)
 for more details and examples.
 
 #### `only:refs` / `except:refs`