| [Shell](https://docs.gitlab.com/runner/executors/shell.html) | Locally, stored under the `gitlab-runner` user's home directory: `/home/gitlab-runner/cache/<user>/<project>/<cache-key>/cache.zip`. |
| [Docker](https://docs.gitlab.com/runner/executors/docker.html) | Locally, stored under [Docker volumes](https://docs.gitlab.com/runner/executors/docker.html#the-builds-and-cache-storage): `/var/lib/docker/volumes/<volume-id>/_data/<user>/<project>/<cache-key>/cache.zip`. |
| [Docker machine](https://docs.gitlab.com/runner/executors/docker_machine.html)(autoscale runners) | Behaves the same as the Docker executor. |
| [Shell](https://docs.gitlab.com/runner/executors/shell.html) | Locally, under the `gitlab-runner` user's home directory: `/home/gitlab-runner/cache/<user>/<project>/<cache-key>/cache.zip`. |
| [Docker](https://docs.gitlab.com/runner/executors/docker.html) | Locally, under [Docker volumes](https://docs.gitlab.com/runner/executors/docker.html#the-builds-and-cache-storage): `/var/lib/docker/volumes/<volume-id>/_data/<user>/<project>/<cache-key>/cache.zip`. |
| [Docker Machine](https://docs.gitlab.com/runner/executors/docker_machine.html)(autoscale runners) | The same as the Docker executor. |
If you use cache and artifacts to store the same path in your jobs, the cache might
be overwritten because caches are restored before artifacts.
### How archiving and extracting works
This example has two jobs that belong to two consecutive stages:
This example shows two jobs in two consecutive stages:
```yaml
stages:
...
...
@@ -449,7 +447,7 @@ job B:
-vendor/
```
If you have one machine with one runner installed, and all jobs for your project
If one machine has one runner installed, then all jobs for your project
run on the same host:
1. Pipeline starts.
...
...
@@ -489,27 +487,54 @@ different architecture (for example, when the cache includes binary files). Also
because the different steps might be executed by runners running on different
machines, it is a safe default.
## Clearing the cache
Runners use [cache](../yaml/README.md#cache) to speed up the execution
of your jobs by reusing existing data. This can sometimes lead to
inconsistent behavior.
There are two ways to start with a fresh copy of the cache.
### Clear the cache by changing `cache:key`
Change the value for `cache: key` in your `.gitlab-ci.yml` file.
The next time the pipeline runs, the cache is stored in a different location.
### Clear the cache manually
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41249) in GitLab 10.4.
You can clear the cache in the GitLab UI:
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **CI/CD > Pipelines** page.
1. In the top right, select **Clear runner caches**.
On the next commit, your CI/CD jobs use a new cache.
NOTE:
Each time you clear the cache manually, the [internal cache name](#where-the-caches-are-stored) is updated. The name uses the format `cache-<index>`, and the index increments by one. The old cache is not deleted. You can manually delete these files from the runner storage.
## Troubleshooting
### Cache mismatch
In the following table, you can see some reasons where you might hit a cache
mismatch and a few ideas how to fix it.
If you have a cache mismatch, follow these steps to troubleshoot.
| Reason of a cache mismatch | How to fix it |
| -------------------------- | ------------- |
| You use multiple standalone runners (not in autoscale mode) attached to one project without a shared cache | Use only one runner for your project or use multiple runners with distributed cache enabled |
| You use runners in autoscale mode without a distributed cache enabled | Configure the autoscale runner to use a distributed cache |
| The machine the runner is installed on is low on disk space or, if you've set up distributed cache, the S3 bucket where the cache is stored doesn't have enough space | Make sure you clear some space to allow new caches to be stored. There's no automatic way to do this. |
| Reason for a cache mismatch | How to fix it |
| --------------------------- | ------------- |
| You use multiple standalone runners (not in autoscale mode) attached to one project without a shared cache. | Use only one runner for your project or use multiple runners with distributed cache enabled. |
| You use runners in autoscale mode without a distributed cache enabled. | Configure the autoscale runner to use a distributed cache. |
| The machine the runner is installed on is low on disk space or, if you've set up distributed cache, the S3 bucket where the cache is stored doesn't have enough space. | Make sure you clear some space to allow new caches to be stored. There's no automatic way to do this. |
| You use the same `key` for jobs where they cache different paths. | Use different cache keys to that the cache archive is stored to a different location and doesn't overwrite wrong caches. |
Let's explore some examples.
#### Examples
#### Cache mismatch example 1
Let's assume you have only one runner assigned to your project, so the cache
is stored in the runner's machine by default.
If you have only one runner assigned to your project, the cache
is stored on the runner's machine by default.
Two jobs could cause caches to be overwritten if they have the same cache key, but
they cache a different path:
If two jobs have the same cache key but a different path, the caches can be overwritten.
For example:
```yaml
stages:
...
...
@@ -541,11 +566,14 @@ job B:
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.
To fix this issue, use different `keys` for each job.
#### Cache mismatch example 2
In this example, you have more than one runner assigned to your
project, and distributed cache is not enabled.
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
The second time the pipeline runs, you want `job A` and `job B` to re-use their cache (which in this case
is different):
```yaml
...
...
@@ -571,46 +599,4 @@ job B:
```
Even if the `key` is different, the cached files might get "cleaned" before each
stage if the jobs run on different runners in the subsequent pipelines.
## Clearing the cache
Runners use [cache](../yaml/README.md#cache) to speed up the execution
of your jobs by reusing existing data. This however, can sometimes lead to an
inconsistent behavior.
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 is stored in a different location.
### Clearing the cache manually
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41249) in GitLab 10.4.
If you want to avoid editing `.gitlab-ci.yml`, you can clear the cache
via the GitLab UI:
1. Navigate to your project's **CI/CD > Pipelines** page.
1. Click on the **Clear runner caches** button to clean up the cache.
1. On the next push, your CI/CD job uses a new cache.
NOTE:
Each time you clear the cache manually, the [internal cache name](#where-the-caches-are-stored) is updated. The name uses the format `cache-<index>`, and the index increments by one each time. The old cache is not deleted. You can manually delete these files from the runner storage.
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
stage if the jobs run on different runners in subsequent pipelines.
