Commit 3d0122af authored by Marcel Amirault's avatar Marcel Amirault

Merge branch 'selhorn-caching-another' into 'master'

Edited Caching topic for style

See merge request gitlab-org/gitlab!64144
parents 7342e809 0349e58a
......@@ -19,62 +19,60 @@ Use cache for dependencies, like packages you download from the internet.
Cache is stored where GitLab Runner is installed and uploaded to S3 if
[distributed cache is enabled](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching).
- You can define it per job by using the `cache:` keyword. Otherwise it is disabled.
- You can define it per job so that:
- Subsequent pipelines can use it.
- Subsequent jobs in the same pipeline can use it, if the dependencies are identical.
- You cannot share it between projects.
Use artifacts to pass intermediate build results between stages.
Artifacts are generated by a job, stored in GitLab, and can be downloaded.
- You can define artifacts per job. Subsequent jobs in later stages of the same
pipeline can use them.
- You can't use the artifacts in a different pipeline.
Both artifacts and caches define their paths relative to the project directory, and
can't link to files outside it.
### Cache
- Define cache per job by using the `cache:` keyword. Otherwise it is disabled.
- Subsequent pipelines can use the cache.
- Subsequent jobs in the same pipeline can use the cache, if the dependencies are identical.
- Different projects cannot share the cache.
### Artifacts
- Define artifacts per job.
- Subsequent jobs in later stages of the same pipeline can use artifacts.
- Different projects cannot share artifacts.
Artifacts expire after 30 days unless you define an [expiration time](../yaml/README.md#artifactsexpire_in).
Use [dependencies](../yaml/README.md#dependencies) to control which jobs fetch the artifacts.
Both artifacts and caches define their paths relative to the project directory, and
can't link to files outside it.
## Good caching practices
To ensure maximum availability of the cache, when you declare `cache` in your jobs,
use one or more of the following:
To ensure maximum availability of the cache, do one or more of the following:
- [Tag your runners](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) and use the tag on jobs
that share their cache.
that share the cache.
- [Use runners that are only available to a particular project](../runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects).
- [Use a `key`](../yaml/README.md#cachekey) that fits your workflow (for example,
different caches on each branch). For that, you can take advantage of the
[predefined CI/CD variables](../variables/README.md#predefined-cicd-variables).
- [Use a `key`](../yaml/README.md#cachekey) that fits your workflow. For example,
you can configure a different cache for each branch.
For runners to work with caches efficiently, you must do one of the following:
- Use a single runner for all your jobs.
- Use multiple runners (in autoscale mode or not) that use
- 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 (like shared runners on GitLab.com).
- Use multiple runners (not in autoscale mode) of the same architecture that
share a common network-mounted directory (using NFS or something similar)
where the cache is stored.
Read about the [availability of the cache](#availability-of-the-cache)
to learn more about the internals and get a better idea how cache works.
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.
- 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.
### Share caches between jobs in the same branch
Define a cache with the `key: ${CI_COMMIT_REF_SLUG}` so that jobs of each
branch always use the same cache:
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 is safe from accidentally overwriting the cache, but merge requests
get slow first pipelines. The next time a new commit is pushed to the branch, the
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:
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment