Caches with the CLI

List, create, test, update and delete S3-compatible runner caches, and attach them to runners from the terminal.

A cache stores the GitLab CI cache: of your runners in an S3-compatible bucket. Caches in the manual explains providers, sharing and what recreates runners. Reading caches needs the runners:read scope, which the CLI’s login token has; changes and cache test need runners:write. An explicit cache id adds no cache-read requirement: cache test --id, cache delete --id and runner create --cache <id> work with runners:write alone, while runner update still needs runners:read and runners:write because it reads the runner first. Resolving a cache name needs runners:read:

manage-runners auth login --profile default --scope runners:write

List and inspect

manage-runners cache list
manage-runners cache get --name "Team cache"

Each cache shows its connection settings, whether it is shared, and usedBy, the runners that use it. The secret key is never returned. --name matches the exact name first and then a unique name in any letter case.

Create a cache

Pass the secret key on standard input or through a named environment variable, never as a flag value:

printf '%s' "$S3_SECRET_KEY" | manage-runners cache create \
  --name "Team cache" \
  --server-address fsn1.your-objectstorage.com \
  --bucket ci-cache \
  --region fsn1 \
  --access-key-id "$S3_ACCESS_KEY_ID" \
  --secret-key-stdin

Test a cache

manage-runners cache test --name "Team cache"
manage-runners cache test --server-address s3.eu-central-1.amazonaws.com --bucket ci-cache \
  --region eu-central-1 --access-key-id "$S3_ACCESS_KEY_ID" --secret-key-env S3_SECRET_KEY

The test writes, reads and deletes a small object. It only works for HTTPS endpoints with a public address. A failed test exits with code 7 and CACHE_TEST_FAILED; error.details.result.code names the cause, for example AUTHENTICATION_FAILED, BUCKET_NOT_FOUND, ACCESS_DENIED, TLS_ERROR or UNREACHABLE.

Use a cache on a runner

manage-runners runner create ... --cache "Team cache"
manage-runners runner update --id 812999368881481087 --cache "Team cache" --yes
manage-runners runner update --id 812999368881481087 --no-cache --yes

Changing a runner’s cache recreates an active runner’s server, so runner update asks for confirmation or needs --yes. runner get and runner list show cacheId and cacheName.

Update a cache

manage-runners cache update --name "Team cache" --new-name "Build cache"
manage-runners cache update --name "Team cache" --shared off --yes
printf '%s' "$NEW_SECRET" | manage-runners cache update --id 893531162387173432 --secret-key-stdin --yes

Flags you leave out keep their current values, and the stored secret key is kept unless you pass a new one. Renaming never affects runners. Any other change recreates the servers of the active runners that use the cache: without --yes, the command fails with CACHE_RECREATE_REQUIRED and lists the runners (in a terminal it asks instead). Runners listed with recreate: false are unknown: they are not recreated and keep the previous settings until edited or recreated. With --yes, the output lists the recreated runners under recreatedRunners and reports paid_resource_effect: "recreate". While a runner that uses the cache is being created, resumed or edited, the update fails with RUNNER_LOCKED (exit 6) and names it.

Delete a cache

manage-runners cache delete --id 893531162387173432 --yes --confirm 893531162387173432

A cache that runners use cannot be deleted: the command fails with CACHE_IN_USE (exit 6) and lists the runners. Remove the cache from them first. Deleting does not touch the bucket.