Caches

Share the GitLab CI cache between runners with an S3-compatible bucket, test the connection, and know which changes recreate runners.

GitLab CI’s cache: keyword keeps files such as dependencies between jobs. Without a cache configuration, GitLab Runner stores the cache on the runner’s own server, so it is lost when the runner is paused or recreated and every runner builds its own. A cache in Manage Runners is an S3-compatible bucket that your runners store the CI cache in instead. It survives pausing, resuming and recreating, and runners that share it restore what another runner saved.

Caches belong to an organization and are available on every plan. Owners and editors manage them; viewers see them. A runner uses at most one cache.

S3-compatible providers

Any storage that speaks the S3 API works, for example:

Hetzner Object Storage in the same location as your runners keeps cache traffic in Hetzner’s network. Create the bucket and an access key with your provider first; Manage Runners does not create buckets. The key needs to write, read and delete objects in the bucket.

Create a cache

1. Open Caches in the side menu and select New cache.
2. Fill in the fields:
   • Name: unique within the organization.
   • Server address: the host and an optional port, without https:// and without the bucket.
   • Use plain HTTP: only for servers without TLS. Cache contents and keys then travel unencrypted.
   • Bucket and Region.
   • Path prefix (optional): a folder inside the bucket, so several caches can share one bucket.
   • Share between runners: on by default. See Shared or per runner.
   • Addressing style: Detect automatically fits most providers. Choose path style (server/bucket) or virtual-hosted style (bucket.server) if your provider needs one.
   • Access key ID and Secret access key.
3. Optionally select Test connection, then Create cache.

The secret access key is stored encrypted and never shown again, not even to owners. To change it, enter a new one when you edit the cache; leave the field empty to keep the stored key.

Use a cache on a runner

Select the cache in the Cache field when you create or edit a runner, or choose None. Duplicating a runner keeps its cache. The runner card shows the cache, and Caches lists the runners that use each cache.

GitLab Runner receives the cache settings when its server is created. Selecting, changing or removing the cache of an active runner therefore recreates its server, and the dashboard warns you before you save. A paused runner picks up the change when you resume it.

Shared or per runner

With Share between runners on, every runner that uses the cache reads and writes the same cache entries: a job on one runner can restore the cache another runner saved for the same cache key. This is usually what you want with more than one runner.

With sharing off, GitLab Runner keeps each runner’s entries in its own folder of the bucket (runner/<token>/). The cache still survives pausing and recreating, but runners do not see each other’s entries.

Test connection

Test connection writes a small test object under the path prefix, reads it back and deletes it, using the values in the form. When you edit a cache and leave the secret key empty, the test uses the stored key. The result tells you what failed, for example that the server could not be reached, the TLS certificate is not trusted, the keys were rejected, the bucket does not exist, or the key may not write, read or delete objects.

Test connection only works for HTTPS endpoints whose address is public on the internet. It is disabled for plain HTTP, and servers on private or local networks are refused. You can still save such a cache; check it with a CI job that uses cache: instead. Each member can run 10 tests per organization within 10 minutes.

Edit a cache

Select Edit on the cache. Renaming a cache never affects runners. Changing anything else, including sharing and the secret key, changes the configuration of every runner that uses the cache: before saving, the dashboard lists the active runners whose servers it will recreate and asks you to confirm. Their running jobs are interrupted. Paused runners use the new settings when they are resumed.

Runners in the Unknown state are listed too, but they are not recreated: a server that Manage Runners cannot reach keeps the previous cache settings, also when it comes back as active, until its server is recreated, for example when you pause and resume the runner or make an edit that recreates the server. While a runner that uses the cache is being created, resumed or edited, saving fails and names that runner; try again when it is done.

Delete a cache

Select Delete and confirm. A cache that runners still use cannot be deleted; the dashboard names those runners so you can select another cache or None on them first. Deleting a cache only removes its configuration from Manage Runners. The bucket and its objects stay with your provider.