diff options
Diffstat (limited to 'doc/ci/caching/index.md')
| -rw-r--r-- | doc/ci/caching/index.md | 68 |
1 files changed, 59 insertions, 9 deletions
diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index e9d3dae3837..1822e610dad 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -99,7 +99,10 @@ the global fallback cache is fetched every time a cache is not found. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110467) in GitLab 16.0 -Each cache entry supports up-to 5 fallback keys: +Each cache entry supports up to five fallback keys with the [`fallback_keys` keyword](../yaml/index.md#cachefallback_keys). +When a job does not find a cache key, the job attempts to retrieve a fallback cache instead. +Fallback keys are searched in order until a cache is found. If no cache is found, +the job runs without using a cache. For example: ```yaml test-job: @@ -114,11 +117,25 @@ test-job: script: - bundle config set --local path 'vendor/ruby' - bundle install - - yarn install --cache-folder .yarn-cache - echo Run tests... ``` -Fallback keys follows the same processing logic as `cache:key`, meaning that the fullname may include a `-$index` (based on cache clearance) and `-protected`/`-non_protected` (if cache separation enabled on protected branches) suffixes. +In this example: + +1. The job looks for the `cache-$CI_COMMIT_REF_SLUG` cache. +1. If `cache-$CI_COMMIT_REF_SLUG` is not found, the job looks for `cache-$CI_DEFAULT_BRANCH` + as a fallback option. +1. If `cache-$CI_DEFAULT_BRANCH` is also not found, the job looks for `cache-default` + as a second fallback option. +1. If none are found, the job downloads all the Ruby dependencies without using a cache, + but creates a new cache for `cache-$CI_COMMIT_REF_SLUG` when the job completes. + +Fallback keys follow the same processing logic as `cache:key`: + +- If you [clear caches manually](#clear-the-cache-manually), per-cache fallback keys are appended + with an index like other cache keys. +- If the [**Use separate caches for protected branches** setting](#cache-key-names) is enabled, + per-cache fallback keys are appended with `-protected` or `-non_protected`. ### Global fallback key @@ -244,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 @@ -352,7 +402,7 @@ variables: PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip" # Pip's cache doesn't store the python packages -# https://pip.pypa.io/en/stable/reference/pip_install/#caching +# https://pip.pypa.io/en/stable/topics/caching/ cache: paths: - .cache/pip @@ -485,7 +535,7 @@ be overwritten because caches are restored before artifacts. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330047) in GitLab 15.0. -A suffix is added to the cache key, with the exception of the [fallback cache key](#use-a-fallback-cache-key). +A suffix is added to the cache key, with the exception of the [global fallback cache key](#global-fallback-key). As an example, assuming that `cache.key` is set to `$CI_COMMIT_REF_SLUG`, and that we have two branches `main` and `feature`, then the following table represents the resulting cache keys: @@ -507,8 +557,8 @@ and should only be disabled in an environment where all users with Developer rol To use the same cache for all branches: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > CI/CD**. 1. Expand **General pipelines**. 1. Clear the **Use separate caches for protected branches** checkbox. 1. Select **Save changes**. @@ -604,8 +654,8 @@ The next time the pipeline runs, the cache is stored in a different location. You can clear the cache in the GitLab UI: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **CI/CD > Pipelines**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Build > Pipelines**. 1. In the upper-right corner, select **Clear runner caches**. On the next commit, your CI/CD jobs use a new cache. |