Docs feedback: No docs for how to create initial caches for "fallback_keys"

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Close this issue

All documentation on fallback_keys fails to explain when the caches for the configured fallback_keys are created, or updated.

• https://docs.gitlab.com/ee/ci/caching/#use-a-fallback-cache-key
• https://docs.gitlab.com/ee/ci/yaml/index.html#cachefallback_keys

It is heavily implied (i.e. it is the only conclusion you could draw from the documentation) that it is impossible to create a cache under a fallback_key. This of course makes no sense, since why have a feature that can't be used? So I have to assume the documentation is lacking, and fallback_keys are usable. To be usable they would have to be created before they are retrieved.

To be specific, in the yaml page, there is only information about retrieval:

Use cache:fallback_keys to specify a list of keys to try to restore cache from if there is no cache found for the cache:key. Caches are retrieved in the order specified in the fallback_keys section.

Combined with the caching page:

let's pretend I copied the entire giant section of documentation into here, which only mentions:
- retrieving / downloading fallback_key caches, and
- pushing primary caches

No mentions of pushing fallback_keys or how that might work. If the fallback_keys are increasingly less specific than, say, a Gemfile.lock file-based key, they would be retrieved every time a commit changes the Gemfile.lock.

Do fallback_keys get updated in those same jobs where they are used? If so, does the job upload the same bundle to multiple cache keys? It must, because it is documented that the missed cache key will be filled in upon job success.

The documentation goes into great detail on how to use a fallback_key, but skips the most important part. How, when, why are they created in the first place. It explains how and when fallback_key caches are retrieved, and what happens if they don't exist... How do we make them exist?

Also notable:

• it appears that the push-pull settings only apply to the primary cache key. Is that accurate?
• It appears implied that the cache:key:prefix can be only used with the primary cache key, not the fallback_keys. Is that accurate?