Add latest changes from gitlab-org/gitlab@master

3 files changed, 39 insertions, 0 deletions

diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md
index d085c994f73..0ba1f9b02bc 100644
--- a/doc/ci/caching/index.md
+++ b/doc/ci/caching/index.md
@@ -261,6 +261,39 @@ cache:
   key: $CI_JOB_NAME
 ```
 
+### Use a variable to control a job's cache policy
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371480) in GitLab 16.1.
+
+To reduce duplication of jobs where the only difference is the pull policy, you can use a [CI/CD variable](../variables/index.md).
+
+For example:
+
+```yaml
+conditional-policy:
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+      variables:
+        POLICY: pull-push
+    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
+      variables:
+        POLICY: pull
+  stage: build
+  cache:
+    key: gems
+    policy: $POLICY
+    paths:
+      - vendor/bundle
+  script:
+    - echo "This job pulls and pushes the cache depending on the branch"
+    - echo "Downloading dependencies..."
+```
+
+In this example, the job's cache policy is:
+
+- `pull-push` for changes to the default branch.
+- `pull` for changes to other branches.
+
 ### Cache Node.js dependencies
 
 If your project uses [npm](https://www.npmjs.com/) to install Node.js
diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md
index c20d9be51e7..aac25356efa 100644
--- a/doc/ci/variables/where_variables_can_be_used.md
+++ b/doc/ci/variables/where_variables_can_be_used.md
@@ -28,6 +28,7 @@ There are two places defined variables can be used. On the:
 | [`artifacts:name`](../yaml/index.md#artifactsname)                    | yes              | Runner                 | The variable expansion is made by GitLab Runner's shell environment. |
 | [`before_script`](../yaml/index.md#before_script)                     | yes              | Script execution shell | The variable expansion is made by the [execution shell environment](#execution-shell-environment) |
 | [`cache:key`](../yaml/index.md#cachekey)                              | yes              | Runner                 | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism). |
+| [`cache:policy`](../yaml/index.md#cachepolicy)                        | yes              | Runner                 | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism). |
 | [`environment:name`](../yaml/index.md#environmentname)                | yes              | GitLab                 | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/><br/>- `CI_ENVIRONMENT_*` variables.<br/>- [Persisted variables](#persisted-variables). |
 | [`environment:url`](../yaml/index.md#environmenturl)                  | yes              | GitLab                 | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab.<br/><br/>Supported are all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules).<br/><br/>Not supported are variables defined in the GitLab Runner `config.toml` and variables created in the job's `script`. |
 | [`environment:auto_stop_in`](../yaml/index.md#environmentauto_stop_in)| yes              | GitLab                 | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab.<br/><br/> The value of the variable being substituted should be a period of time in a human readable natural language form. See [possible inputs](../yaml/index.md#environmentauto_stop_in) for more information.|
diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md
index 50068982b38..2cabb4bbaab 100644
--- a/doc/ci/yaml/index.md
+++ b/doc/ci/yaml/index.md
@@ -1453,6 +1453,7 @@ Must be used with `cache: paths`, or nothing is cached.
 - `pull`
 - `push`
 - `pull-push` (default)
+- [CI/CD variables](../variables/where_variables_can_be_used.md#gitlab-ciyml-file).
 
 **Example of `cache:policy`**:
 
@@ -1480,6 +1481,10 @@ faster-test-job:
     - echo "Running tests..."
 ```
 
+**Related topics**:
+
+- You can [use a variable to control a job's cache policy](../caching/index.md#use-a-variable-to-control-a-jobs-cache-policy).
+
 #### `cache:fallback_keys`
 
 Use `cache:fallback_keys` to specify a list of keys to try to restore cache from