diff options
Diffstat (limited to 'doc/ci/caching/index.md')
| -rw-r--r-- | doc/ci/caching/index.md | 32 |
1 files changed, 16 insertions, 16 deletions
diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index dfa92d469bc..3f1aea0a4d9 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -38,12 +38,12 @@ runtime dependencies needed to compile the project: be configured to pass intermediate build results between stages, this should be done with artifacts instead. -- `artifacts`: **Use for stage results that will be passed between stages.** +- `artifacts`: **Use for stage results that are passed between stages.** Artifacts are files generated by a job which are stored and uploaded, and can then be fetched and used by jobs in later stages of the **same pipeline**. In other words, [you can't create an artifact in job-A in stage-1, and then use this artifact in job-B in stage-1](https://gitlab.com/gitlab-org/gitlab/-/issues/25837). - This data will not be available in different pipelines, but is available to be downloaded + This data is be available in different pipelines, but is available to be downloaded from the UI. The name `artifacts` sounds like it's only useful outside of the job, like for downloading @@ -87,7 +87,7 @@ cache, when declaring `cache` in your jobs, use one or a mix of the following: - [Tag your runners](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) and use the tag on jobs that share their cache. - [Use sticky runners](../runners/README.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) - that will be only available to a particular project. + that are only available to a particular project. - [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 [CI/CD predefined variables](../variables/README.md#predefined-environment-variables). @@ -106,7 +106,7 @@ of the following must be true: 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 will be stored. + where the cache is stored. TIP: **Tip:** Read about the [availability of the cache](#availability-of-the-cache) @@ -125,7 +125,7 @@ cache: While this feels like it might be safe from accidentally overwriting the cache, it means merge requests get slow first pipelines, which might be a bad developer experience. The next time a new commit is pushed to the branch, the -cache will be re-used. +cache is re-used. To enable per-job and per-branch caching: @@ -160,7 +160,7 @@ cache: ### Disabling cache on specific jobs -If you have defined the cache globally, it means that each job will use the +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 disable it completely, use an empty hash: @@ -431,9 +431,9 @@ Here's what happens behind the scenes: 1. `script` is executed. 1. Pipeline finishes. -By using a single runner on a single machine, you'll not have the issue where +By using a single runner on a single machine, you don't have the issue where `job B` might execute on a runner different from `job A`, thus guaranteeing the -cache between stages. That will only work if the build goes from stage `build` +cache between stages. That only works if the build goes from stage `build` to `test` in the same runner/machine, otherwise, you [might not have the cache available](#cache-mismatch). @@ -442,7 +442,7 @@ During the caching process, there's also a couple of things to consider: - If some other job, with another cache configuration had saved its cache in the same zip file, it is overwritten. If the S3 based shared cache is used, the file is additionally uploaded to S3 to an object based on the cache - key. So, two jobs with different paths, but the same cache key, will overwrite + key. So, two jobs with different paths, but the same cache key, overwrites their cache. - When extracting the cache from `cache.zip`, everything in the zip file is extracted in the job's working directory (usually the repository which is @@ -450,7 +450,7 @@ During the caching process, there's also a couple of things to consider: things in the archive of `job B`. The reason why it works this way is because the cache created for one runner -often will not be valid when used by a different one which can run on a +often isn't valid when used by a different one which can run on a **different architecture** (e.g., when the cache includes binary files). And since the different steps might be executed by runners running on different machines, it is a safe default. @@ -472,7 +472,7 @@ Let's explore some examples. #### Examples Let's assume you have only one runner assigned to your project, so the cache -will be stored in the runner's machine by default. If two jobs, A and B, +is stored in the runner's machine by default. If two jobs, A and B, have the same cache key, but they cache different paths, cache B would overwrite cache A, even if their `paths` don't match: @@ -506,15 +506,15 @@ job B: 1. `job B` runs. 1. The previous cache, if any, is unzipped. 1. `vendor/` is cached as cache.zip and overwrites the previous one. -1. The next time `job A` runs it will use the cache of `job B` which is different - and thus will be ineffective. +1. The next time `job A` runs it uses the cache of `job B` which is different + and thus isn't effective. To fix that, use different `keys` for each job. In another case, let's assume you have more than one runner assigned to your project, but the distributed cache is not enabled. The second time the pipeline is run, we want `job A` and `job B` to re-use their cache (which in this case -will be different): +is different): ```yaml stages: @@ -553,7 +553,7 @@ To start with a fresh copy of the cache, there are two ways to do that. ### Clearing the cache by changing `cache:key` All you have to do is set a new `cache: key` in your `.gitlab-ci.yml`. In the -next run of the pipeline, the cache will be stored in a different location. +next run of the pipeline, the cache is stored in a different location. ### Clearing the cache manually @@ -567,7 +567,7 @@ via GitLab's UI:  -1. On the next push, your CI/CD job will use a new cache. +1. On the next push, your CI/CD job uses a new cache. Behind the scenes, this works by increasing a counter in the database, and the value of that counter is used to create the key for the cache by appending an |