Merge branch 'docs-update-only-to-rules' into 'master'

Update CI/CD examples to use rules

See merge request gitlab-org/gitlab!63996

doc/ci/docker/using_kaniko.md

@@ -99,8 +99,8 @@ build:
        KANIKOCFG="${KANIKOCFG} }"
        echo "${KANIKOCFG}" > /kaniko/.docker/config.json
     - /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile $KANIKOPROXYBUILDARGS --destination $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
-  only:
-    - tags
+  rules:
+    - if: $CI_COMMIT_TAG
 ```
 
 ## Using a registry with a custom certificate

doc/ci/environments/index.md

@@ -99,10 +99,10 @@ deploy_review:
   environment:
     name: review/$CI_COMMIT_REF_NAME
     url: https://$CI_ENVIRONMENT_SLUG.example.com
-  only:
-    - branches
-  except:
-    - master
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+      when: never
+    - if: $CI_COMMIT_BRANCH
 ```
 
 In this example:
@@ -158,8 +158,8 @@ deploy_prod:
     name: production
     url: https://example.com
   when: manual
-  only:
-    - master
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 ```
 
 The `when: manual` action:
@@ -200,8 +200,8 @@ deploy:
     url: https://example.com
     kubernetes:
       namespace: production
-  only:
-    - master
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 ```
 
 When you use the GitLab Kubernetes integration to deploy to a Kubernetes cluster,

doc/ci/migration/jenkins.md

@@ -349,12 +349,14 @@ variable entry.
 
 GitLab does support a [`when` keyword](../yaml/README.md#when) which is used to indicate when a job should be
 run in case of (or despite) failure, but most of the logic for controlling pipelines can be found in
-our very powerful [`only/except` rules system](../yaml/README.md#only--except)
-(see also our [advanced syntax](../yaml/README.md#only--except)):
+our very powerful [`rules` system](../yaml/README.md#rules):
 
 ```yaml
 my_job:
-  only: [branches]
+  script:
+    - echo
+  rules:
+    - if: $CI_COMMIT_BRANCH
 ```
 
 ## Additional resources

doc/ci/parent_child_pipelines.md

@@ -38,7 +38,7 @@ set of concurrently running child pipelines, but within the same project:
 
 Child pipelines work well with other GitLab CI/CD features:
 
-- Use [`only: changes`](yaml/README.md#onlychanges--exceptchanges) to trigger pipelines only when
+- Use [`rules: changes`](yaml/README.md#ruleschanges) to trigger pipelines only when
   certain files change. This is useful for monorepos, for example.
 - Since the parent pipeline in `.gitlab-ci.yml` and the child pipeline run as normal
   pipelines, they can have their own behaviors and sequencing in relation to triggers.

doc/ci/pipelines/schedules.md

@@ -8,9 +8,6 @@ type: reference, howto
 
 # Pipeline schedules **(FREE)**
 
-> - Introduced in GitLab 9.1 as [Trigger Schedule](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10533).
-> - [Renamed to Pipeline Schedule](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10853) in GitLab 9.2.
-
 Pipelines are normally run based on certain conditions being met. For example, when a branch is pushed to repository.
 
 Pipeline schedules can be used to also run [pipelines](index.md) at specific intervals. For example:
@@ -54,31 +51,29 @@ is installed on.
 
 ### Using variables
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12328) in GitLab 9.4.
-
 You can pass any number of arbitrary variables. They are available in
 GitLab CI/CD so that they can be used in your [`.gitlab-ci.yml` file](../../ci/yaml/README.md).
 
 ![Scheduled pipeline variables](img/pipeline_schedule_variables.png)
 
-### Using only and except
+### Using `rules`
 
 To configure a job to be executed only when the pipeline has been
-scheduled (or the opposite), use
-[only and except](../yaml/README.md#only--except) configuration keywords.
+scheduled, use the [`rules`](../yaml/README.md#rules) keyword.
 
-In the example below `make world` runs in scheduled pipelines, and `make build` runs in pipelines that are not scheduled:
+In this example, `make world` runs in scheduled pipelines, and `make build`
+runs in branch and tag pipelines:
 
 ```yaml
 job:on-schedule:
-  only:
-    - schedules
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"
   script:
     - make world
 
 job:
-  except:
-    - schedules
+  rules:
+    - if: $CI_PIPELINE_SOURCE = "push"
   script:
     - make build
 ```

doc/ci/triggers/README.md

@@ -57,8 +57,8 @@ trigger_pipeline:
   stage: deploy
   script:
     - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"
-  only:
-    - tags
+  rules:
+    - if: $CI_COMMIT_TAG
 ```
 
 Pipelines triggered that way also expose a special variable:
@@ -83,8 +83,8 @@ build_submodule:
     - apt update && apt install -y unzip
     - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN"
     - unzip artifacts.zip
-  only:
-    - tags
+  rules:
+    - if: $CI_COMMIT_TAG
 ```
 
 This allows you to use that for multi-project pipelines and download artifacts
@@ -163,8 +163,8 @@ trigger_pipeline:
   stage: deploy
   script:
     - 'curl --request POST --form token=TOKEN --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"'
-  only:
-    - tags
+  rules:
+    - if: $CI_COMMIT_TAG
 ```
 
 This means that whenever a new tag is pushed on project A, the job runs and the

doc/ci/variables/where_variables_can_be_used.md

@@ -35,7 +35,7 @@ There are two places defined variables can be used. On the:
 | `cache:key`                                | yes              | Runner                 | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism)                                                                                                                                                                                                                                                                                   |
 | `artifacts:name`                           | yes              | Runner                 | The variable expansion is made by GitLab Runner's shell environment                                                                                                                                                                                                                                                                                                                                                               |
 | `script`, `before_script`, `after_script`  | yes              | Script execution shell | The variable expansion is made by the [execution shell environment](#execution-shell-environment)                                                                                                                                                                                                                                                                                                                                 |
-| `only:variables:[]`, `except:variables:[]`, `rules:if` | no               | n/a                    | The variable must be in the form of `$variable`. Not supported are the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables).                                                                                            |
+| `only:variables:[]`, `except:variables:[]`, `rules:if` | no   | n/a                    | The variable must be in the form of `$variable`. Not supported are the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables).                                                                                        |
 
 ### `config.toml` file
 
@@ -193,7 +193,6 @@ my-job:
     name: review/$CI_JOB_STAGE/deploy
   script:
     - 'deploy staging'
-  only:
-    variables:
-      - $STAGING_SECRET == 'something'
+  rules:
+    - if: $STAGING_SECRET == 'something'
 ```

doc/ci/yaml/README.md

@@ -991,8 +991,8 @@ but you can use as many as eleven. The following example has two levels of inher
 
 ```yaml
 .tests:
-  only:
-    - pushes
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "push"
 
 .rspec:
   extends: .tests
@@ -1028,9 +1028,9 @@ levels. For example:
   variables:
     URL: "http://my-url.internal"
     IMPORTANT_VAR: "the details"
-  only:
-    - main
-    - stable
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+    - if: $CI_COMMIT_BRANCH == "stable"
   tags:
     - production
   script:
@@ -1061,9 +1061,9 @@ rspec:
     URL: "http://docker-url.internal"
     IMPORTANT_VAR: "the details"
     GITLAB: "is-awesome"
-  only:
-    - main
-    - stable
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+    - if: $CI_COMMIT_BRANCH == "stable"
   tags:
     - docker
   image: alpine
@@ -2333,8 +2333,8 @@ To protect a manual job:
        name: production
        url: https://example.com
      when: manual
-     only:
-       - main
+     rules:
+       - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    ```
 
 1. In the [protected environments settings](../environments/protected_environments.md#protecting-environments),
@@ -3281,8 +3281,8 @@ Create artifacts only for tags (`default-job` doesn't create artifacts):
 default-job:
   script:
     - mvn test -U
-  except:
-    - tags
+  rules:
+    - if: $CI_COMMIT_BRANCH
 
 release-job:
   script:
@@ -3290,8 +3290,8 @@ release-job:
   artifacts:
     paths:
       - target/*.war
-  only:
-    - tags
+  rules:
+    - if: $CI_COMMIT_TAG
 ```
 
 You can use wildcards for directories too. For example, if you want to get all the files inside the directories that end with `xyz`:
@@ -4370,7 +4370,10 @@ job:
     description: 'Release description'
 ```
 
-It is also possible to create any unique tag, in which case `only: tags` is not mandatory.
+It is also possible for the release job to automatically create a new unique tag. In that case,
+do not use [`rules`](#rules) or [`only`](#only--except) to configure the job to
+only run for tags.
+
 A semantic versioning example:
 
 ```yaml
@@ -4626,8 +4629,8 @@ pages:
   artifacts:
     paths:
       - public
-  only:
-    - main
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 ```
 
 View the [GitLab Pages user documentation](../../user/project/pages/index.md).

doc/ci/yaml/includes.md

@@ -111,8 +111,8 @@ production:
   environment:
     name: production
     url: https://$CI_PROJECT_PATH_SLUG.$KUBE_INGRESS_BASE_DOMAIN
-  only:
-    - main
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 ```
 
 Content of `.gitlab-ci.yml`: