diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-06-17 21:10:22 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-06-17 21:10:22 +0300 |
commit | 6f79cf2bd654a018387313de70b9dd45a373ce72 (patch) | |
tree | 1de67c412e2a97dcf036ec1a3b46648fc341e5de /doc/ci/caching | |
parent | 5c5e86aa5c6e8be8424a92846cd0dfa8e72944e2 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/ci/caching')
-rw-r--r-- | doc/ci/caching/index.md | 131 |
1 files changed, 94 insertions, 37 deletions
diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index 3c9a796a9f2..136c6c282df 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -57,55 +57,69 @@ For runners to work with caches efficiently, you must do one of the following: - Use multiple runners that have [distributed caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching), where the cache is stored in S3 buckets. Shared runners on GitLab.com behave this way. These runners can be in autoscale mode, - but they don't have to be. + but they don't have to be. - Use multiple runners with the same architecture and have these runners share a common network-mounted directory to store the cache. This directory should use NFS or something similar. - These runners must be in autoscale mode. + These runners must be in autoscale mode. -### Share caches between jobs in the same branch - -To have jobs for each branch use the same cache, define a cache with the `key: ${CI_COMMIT_REF_SLUG}`: - -```yaml -cache: - key: ${CI_COMMIT_REF_SLUG} -``` +## Use multiple caches -This configuration prevents you from accidentally overwriting the cache. However, the -first pipeline for a merge request is slow. The next time a commit is pushed to the branch, the -cache is re-used and jobs run faster. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32814) in GitLab 13.10. +> - [Feature Flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321877), in GitLab 13.12. -To enable per-job and per-branch caching: +You can have a maximum of four caches: ```yaml -cache: - key: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG" +test-job: + stage: build + cache: + - key: + files: + - Gemfile.lock + paths: + - vendor/ruby + - key: + files: + - yarn.lock + paths: + - .yarn-cache/ + script: + - bundle install --path=vendor + - yarn install --cache-folder .yarn-cache + - echo Run tests... ``` -To enable per-stage and per-branch caching: +If multiple caches are combined with a [Fallback cache key](#fallback-cache-key), +the fallback cache is fetched every time a cache is not found. -```yaml -cache: - key: "$CI_JOB_STAGE-$CI_COMMIT_REF_SLUG" -``` +## Fallback cache key -### Share caches across jobs in different branches +> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1534) in GitLab Runner 13.4. -To share a cache across all branches and all jobs, use the same key for everything: +You can use the `$CI_COMMIT_REF_SLUG` [predefined variable](../variables/predefined_variables.md) +to specify your [`cache:key`](../yaml/README.md#cachekey). For example, if your +`$CI_COMMIT_REF_SLUG` is `test` you can set a job to download cache that's tagged with `test`. -```yaml -cache: - key: one-key-to-rule-them-all -``` +If a cache with this tag is not found, you can use `CACHE_FALLBACK_KEY` to +specify a cache to use when none exists. -To share caches between branches, but have a unique cache for each job: +In the following example, if the `$CI_COMMIT_REF_SLUG` is not found, the job uses the key defined +by the `CACHE_FALLBACK_KEY` variable: ```yaml -cache: - key: ${CI_JOB_NAME} +variables: + CACHE_FALLBACK_KEY: fallback-key + +job1: + script: + - echo + cache: + key: "$CI_COMMIT_REF_SLUG" + paths: + - binaries/ ``` -### Disable cache for specific jobs +## Disable cache for specific jobs If you have defined the cache globally, it means that each job uses the same definition. You can override this behavior per-job, and if you want to @@ -116,7 +130,7 @@ job: cache: {} ``` -### Inherit global configuration, but override specific settings per job +## Inherit global configuration, but override specific settings per job You can override cache settings without overwriting the global cache by using [anchors](../yaml/README.md#anchors). For example, if you want to override the @@ -124,7 +138,7 @@ You can override cache settings without overwriting the global cache by using ```yaml cache: &global_cache - key: ${CI_COMMIT_REF_SLUG} + key: $CI_COMMIT_REF_SLUG paths: - node_modules/ - public/ @@ -150,6 +164,49 @@ PHP packages, Ruby gems, Python libraries, and others can all be cached. For more examples, check out our [GitLab CI/CD templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). +### Share caches between jobs in the same branch + +To have jobs for each branch use the same cache, define a cache with the `key: $CI_COMMIT_REF_SLUG`: + +```yaml +cache: + key: $CI_COMMIT_REF_SLUG +``` + +This configuration prevents you from accidentally overwriting the cache. However, the +first pipeline for a merge request is slow. The next time a commit is pushed to the branch, the +cache is re-used and jobs run faster. + +To enable per-job and per-branch caching: + +```yaml +cache: + key: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG" +``` + +To enable per-stage and per-branch caching: + +```yaml +cache: + key: "$CI_JOB_STAGE-$CI_COMMIT_REF_SLUG" +``` + +### Share caches across jobs in different branches + +To share a cache across all branches and all jobs, use the same key for everything: + +```yaml +cache: + key: one-key-to-rule-them-all +``` + +To share caches between branches, but have a unique cache for each job: + +```yaml +cache: + key: $CI_JOB_NAME +``` + ### Cache Node.js dependencies If your project is using [npm](https://www.npmjs.com/) to install the Node.js @@ -166,7 +223,7 @@ image: node:latest # Cache modules in between jobs cache: - key: ${CI_COMMIT_REF_SLUG} + key: $CI_COMMIT_REF_SLUG paths: - .npm/ @@ -193,7 +250,7 @@ image: php:7.2 # Cache libraries in between jobs cache: - key: ${CI_COMMIT_REF_SLUG} + key: $CI_COMMIT_REF_SLUG paths: - vendor/ @@ -262,7 +319,7 @@ image: ruby:2.6 # Cache gems in between builds cache: - key: ${CI_COMMIT_REF_SLUG} + key: $CI_COMMIT_REF_SLUG paths: - vendor/ruby @@ -287,7 +344,7 @@ cache: key: files: - Gemfile.lock - prefix: ${CI_JOB_NAME} + prefix: $CI_JOB_NAME paths: - vendor/ruby |