Adds multiple caches per build

* Adds an Entry::Caches to handle multiple caches
* Updates Build#cache
* Updates Entry::Root, Entry::Job, Entry::Default to use Entry::Caches
* Updates Seed::Build and Cache to accomodate multiple caches
* Updates specs to handle multiple cache
* Adds docs and a changelog

app/models/ci/build.rb

@@ -812,14 +812,15 @@ module Ci
     end
 
     def cache
-      cache = options[:cache]
+      cache = Array.wrap(options[:cache])
 
-      if cache && project.jobs_cache_index
-        cache = cache.merge(
-          key: "#{cache[:key]}-#{project.jobs_cache_index}")
+      if project.jobs_cache_index
+        cache = cache.map do |single_cache|
+          single_cache.merge(key: "#{single_cache[:key]}-#{project.jobs_cache_index}")
+        end
       end
 
-      [cache]
+      cache
     end
 
     def credentials

changelogs/unreleased/lm-multiple-cache-per-file.yml

+---
+title: Adds ability to have multiple cache per job
+merge_request: 53410
+author:
+type: changed

config/feature_flags/development/multiple_cache_per_job.yml

+---
+name: multiple_cache_per_job
+introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53410
+rollout_issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/321877
+milestone: '13.10'
+type: development
+group: group::pipeline authoring
+default_enabled: false

doc/ci/yaml/README.md

@@ -2754,7 +2754,62 @@ URI-encoded `%2F`. A value made only of dots (`.`, `%2E`) is also forbidden.
 
 You can specify a [fallback cache key](#fallback-cache-key) to use if the specified `cache:key` is not found.
 
-##### Fallback cache key
+##### Multiple caches
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32814) in GitLab 13.10.
+> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default.
+> - It's disabled on GitLab.com.
+> - It's not recommended for production use.
+> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-multiple-caches). **(FREE SELF)**
+
+WARNING:
+This feature might not be available to you. Check the **version history** note above for details.
+
+You can have a maximum of four caches:
+
+```yaml
+test-job:
+  stage: build
+  cache:
+    - key:
+        files:
+          - Gemfile.lock
+      paths:
+        - vendor/ruby
+    - key:
+        files:
+          - yarn.lock
+      paths:
+        - .yarn-cache/
+  script:
+    - bundle install --path=vendor
+    - yarn install --cache-folder .yarn-cache
+    - echo Run tests...
+```
+
+If multiple caches are combined with a [Fallback cache key](#fallback-cache-key),
+the fallback is fetched multiple times if multiple caches are not found.
+
+##### Enable or disable multiple caches **(FREE SELF)**
+
+The multiple caches feature is under development and not ready for production use.
+It is deployed behind a feature flag that is **disabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
+can enable it.
+
+To enable it:
+
+```ruby
+Feature.enable(:multiple_cache_per_job)
+```
+
+To disable it:
+
+```ruby
+Feature.disable(:multiple_cache_per_job)
+```
+
+#### Fallback cache key
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1534) in GitLab Runner 13.4.
 

lib/gitlab/ci/config/entry/cache.rb

@@ -7,6 +7,40 @@ module Gitlab
         ##
         # Entry that represents a cache configuration
         #
+        class Cache < ::Gitlab::Config::Entry::Simplifiable
+          strategy :Caches, if: -> (config) { Feature.enabled?(:multiple_cache_per_job) }
+          strategy :Cache, if: -> (config) { Feature.disabled?(:multiple_cache_per_job) }
+
+          class Caches < ::Gitlab::Config::Entry::ComposableArray
+            include ::Gitlab::Config::Entry::Validatable
+
+            MULTIPLE_CACHE_LIMIT = 4
+
+            validations do
+              validates :config, presence: true
+
+              validate do
+                unless config.is_a?(Hash) || config.is_a?(Array)
+                  errors.add(:config, 'can only be a Hash or an Array')
+                end
+
+                if config.is_a?(Array) && config.count > MULTIPLE_CACHE_LIMIT
+                  errors.add(:config, "no more than #{MULTIPLE_CACHE_LIMIT} caches can be created")
+                end
+              end
+            end
+
+            def initialize(*args)
+              super
+
+              @key = nil
+            end
+
+            def composable_class
+              Entry::Cache::Cache
+            end
+          end
+
           class Cache < ::Gitlab::Config::Entry::Node
             include ::Gitlab::Config::Entry::Configurable
             include ::Gitlab::Config::Entry::Validatable
@@ -55,6 +89,10 @@ module Gitlab
               result
             end
           end
+
+          class UnknownStrategy < ::Gitlab::Config::Entry::Node
+          end
+        end
       end
     end
   end

lib/gitlab/ci/features.rb

@@ -67,6 +67,10 @@ module Gitlab
       def self.display_codequality_backend_comparison?(project)
         ::Feature.enabled?(:codequality_backend_comparison, project, default_enabled: :yaml)
       end
+
+      def self.multiple_cache_per_job?
+        ::Feature.enabled?(:multiple_cache_per_job, default_enabled: :yaml)
+      end
     end
   end
 end

lib/gitlab/ci/pipeline/seed/build.rb

@@ -28,9 +28,17 @@ module Gitlab
               .fabricate(attributes.delete(:except))
             @rules = Gitlab::Ci::Build::Rules
               .new(attributes.delete(:rules), default_when: 'on_success')
+
+            if multiple_cache_per_job?
+              cache = Array.wrap(attributes.delete(:cache))
+              @cache = cache.map do |cache|
+                Seed::Build::Cache.new(pipeline, cache)
+              end
+            else
               @cache = Seed::Build::Cache
                 .new(pipeline, attributes.delete(:cache))
             end
+          end
 
           def name
             dig(:name)
@@ -197,9 +205,23 @@ module Gitlab
 
           def cache_attributes
             strong_memoize(:cache_attributes) do
+              if multiple_cache_per_job?
+                if @cache.empty?
+                  {}
+                else
+                  { options: { cache: @cache.map(&:attributes) } }
+                end
+              else
                 @cache.build_attributes
               end
             end
+          end
+
+          def multiple_cache_per_job?
+            strong_memoize(:multiple_cache_per_job) do
+              ::Gitlab::Ci::Features.multiple_cache_per_job?
+            end
+          end
 
           # If a job uses `allow_failure:exit_codes` and `rules:allow_failure`
           # we need to prevent the exit codes from being persisted because they

lib/gitlab/ci/pipeline/seed/build/cache.rb

@@ -18,18 +18,18 @@ module Gitlab
               raise ArgumentError, "unknown cache keys: #{local_cache.keys}" if local_cache.any?
             end
 
-            def build_attributes
+            def attributes
               {
-                options: {
-                  cache: {
                 key: key_string,
                 paths: @paths,
                 policy: @policy,
                 untracked: @untracked,
                 when: @when
-                  }.compact.presence
               }.compact
-              }
+            end
+
+            def build_attributes
+              { options: { cache: attributes.presence }.compact }
             end
 
             private

spec/lib/gitlab/ci/config/entry/cache_spec.rb

@@ -7,6 +7,65 @@ RSpec.describe Gitlab::Ci::Config::Entry::Cache do
 
   subject(:entry) { described_class.new(config) }
 
+  context 'with multiple caches' do
+    before do
+      entry.compose!
+    end
+
+    describe '#valid?' do
+      context 'when configuration is valid with a single cache' do
+        let(:config)  { { key: 'key', paths: ["logs/"], untracked: true } }
+
+        it 'is valid' do
+          expect(entry).to be_valid
+        end
+      end
+
+      context 'when configuration is valid with multiple caches' do
+        let(:config) do
+          [
+            { key: 'key', paths: ["logs/"], untracked: true },
+            { key: 'key2', paths: ["logs/"], untracked: true },
+            { key: 'key3', paths: ["logs/"], untracked: true }
+          ]
+        end
+
+        it 'is valid' do
+          expect(entry).to be_valid
+        end
+      end
+
+      context 'when configuration is not a Hash or Array' do
+        let(:config) { 'invalid' }
+
+        it 'is invalid' do
+          expect(entry).not_to be_valid
+        end
+      end
+
+      context 'when entry values contain more than four caches' do
+        let(:config) do
+          [
+            { key: 'key', paths: ["logs/"], untracked: true },
+            { key: 'key2', paths: ["logs/"], untracked: true },
+            { key: 'key3', paths: ["logs/"], untracked: true },
+            { key: 'key4', paths: ["logs/"], untracked: true },
+            { key: 'key5', paths: ["logs/"], untracked: true }
+          ]
+        end
+
+        it 'is invalid' do
+          expect(entry.errors).to eq(["caches config no more than 4 caches can be created"])
+          expect(entry).not_to be_valid
+        end
+      end
+    end
+  end
+
+  context 'with a single cache' do
+    before do
+      stub_feature_flags(multiple_cache_per_job: false)
+    end
     describe 'validations' do
       before do
         entry.compose!
@@ -231,4 +290,5 @@ RSpec.describe Gitlab::Ci::Config::Entry::Cache do
         end
       end
     end
+  end
 end

spec/lib/gitlab/ci/config/entry/job_spec.rb

@@ -526,6 +526,41 @@ RSpec.describe Gitlab::Ci::Config::Entry::Job do
         'variables_value' => nil)
     end
 
+    context 'when job config overrides default config' do
+      before do
+        entry.compose!(deps)
+      end
+
+      let(:config) do
+        { script: 'rspec', image: 'some_image', cache: { key: 'test' } }
+      end
+
+      it 'overrides default config' do
+        expect(entry[:image].value).to eq(name: 'some_image')
+        expect(entry[:cache].value).to eq([key: 'test', policy: 'pull-push', when: 'on_success'])
+      end
+    end
+
+    context 'when job config does not override default config' do
+      before do
+        allow(default).to receive('[]').with(:image).and_return(specified)
+
+        entry.compose!(deps)
+      end
+
+      let(:config) { { script: 'ls', cache: { key: 'test' } } }
+
+      it 'uses config from default entry' do
+        expect(entry[:image].value).to eq 'specified'
+        expect(entry[:cache].value).to eq([key: 'test', policy: 'pull-push', when: 'on_success'])
+      end
+    end
+
+    context 'with multiple_cache_per_job FF disabled' do
+      before do
+        stub_feature_flags(multiple_cache_per_job: false)
+      end
+
       context 'when job config overrides default config' do
         before do
           entry.compose!(deps)
@@ -555,6 +590,7 @@ RSpec.describe Gitlab::Ci::Config::Entry::Job do
           expect(entry[:cache].value).to eq(key: 'test', policy: 'pull-push', when: 'on_success')
         end
       end
+    end
 
     context 'with workflow rules' do
       using RSpec::Parameterized::TableSyntax

spec/lib/gitlab/ci/config/entry/root_spec.rb

@@ -121,6 +121,61 @@ RSpec.describe Gitlab::Ci::Config::Entry::Root do
           end
         end
 
+        describe '#jobs_value' do
+          it 'returns jobs configuration' do
+            expect(root.jobs_value.keys).to eq([:rspec, :spinach, :release])
+            expect(root.jobs_value[:rspec]).to eq(
+              { name: :rspec,
+                      script: %w[rspec ls],
+                      before_script: %w(ls pwd),
+                      image: { name: 'ruby:2.7' },
+                      services: [{ name: 'postgres:9.1' }, { name: 'mysql:5.5' }],
+                      stage: 'test',
+                      cache: [{ key: 'k', untracked: true, paths: ['public/'], policy: 'pull-push', when: 'on_success' }],
+                      variables: { 'VAR' => 'root', 'VAR2' => 'val 2' },
+                      ignore: false,
+                      after_script: ['make clean'],
+                      only: { refs: %w[branches tags] },
+                      scheduling_type: :stage }
+            )
+            expect(root.jobs_value[:spinach]).to eq(
+              { name: :spinach,
+                        before_script: [],
+                        script: %w[spinach],
+                        image: { name: 'ruby:2.7' },
+                        services: [{ name: 'postgres:9.1' }, { name: 'mysql:5.5' }],
+                        stage: 'test',
+                        cache: [{ key: 'k', untracked: true, paths: ['public/'], policy: 'pull-push', when: 'on_success' }],
+                        variables: { 'VAR' => 'root', 'VAR2' => 'val 2' },
+                        ignore: false,
+                        after_script: ['make clean'],
+                        only: { refs: %w[branches tags] },
+                        scheduling_type: :stage }
+            )
+            expect(root.jobs_value[:release]).to eq(
+              { name: :release,
+                        stage: 'release',
+                        before_script: [],
+                        script: ["make changelog | tee release_changelog.txt"],
+                        release: { name: "Release $CI_TAG_NAME", tag_name: 'v0.06', description: "./release_changelog.txt" },
+                        image: { name: "ruby:2.7" },
+                        services: [{ name: "postgres:9.1" }, { name: "mysql:5.5" }],
+                        cache: [{ key: "k", untracked: true, paths: ["public/"], policy: "pull-push", when: 'on_success' }],
+                        only: { refs: %w(branches tags) },
+                        variables: { 'VAR' => 'job', 'VAR2' => 'val 2' },
+                        after_script: [],
+                        ignore: false,
+                        scheduling_type: :stage }
+            )
+          end
+        end
+
+        context 'with multuple_cache_per_job FF disabled' do
+          before do
+            stub_feature_flags(multiple_cache_per_job: false)
+            root.compose!
+          end
+
           describe '#jobs_value' do
             it 'returns jobs configuration' do
               expect(root.jobs_value.keys).to eq([:rspec, :spinach, :release])
@@ -171,6 +226,7 @@ RSpec.describe Gitlab::Ci::Config::Entry::Root do
           end
         end
       end
+    end
 
     context 'when a mix of top-level and default entries is used' do
       let(:hash) do
@@ -187,8 +243,10 @@ RSpec.describe Gitlab::Ci::Config::Entry::Root do
           spinach: { before_script: [], variables: { VAR: 'job' }, script: 'spinach' } }
       end
 
+      context 'with multiple_cache_per_job FF disabled' do
         context 'when composed' do
           before do
+            stub_feature_flags(multiple_cache_per_job: false)
             root.compose!
           end
 
@@ -231,6 +289,50 @@ RSpec.describe Gitlab::Ci::Config::Entry::Root do
         end
       end
 
+      context 'when composed' do
+        before do
+          root.compose!
+        end
+
+        describe '#errors' do
+          it 'has no errors' do
+            expect(root.errors).to be_empty
+          end
+        end
+
+        describe '#jobs_value' do
+          it 'returns jobs configuration' do
+            expect(root.jobs_value).to eq(
+              rspec: { name: :rspec,
+                      script: %w[rspec ls],
+                      before_script: %w(ls pwd),
+                      image: { name: 'ruby:2.7' },
+                      services: [{ name: 'postgres:9.1' }, { name: 'mysql:5.5' }],
+                      stage: 'test',
+                      cache: [{ key: 'k', untracked: true, paths: ['public/'], policy: 'pull-push', when: 'on_success' }],
+                      variables: { 'VAR' => 'root' },
+                      ignore: false,
+                      after_script: ['make clean'],
+                      only: { refs: %w[branches tags] },
+                      scheduling_type: :stage },
+              spinach: { name: :spinach,
+                        before_script: [],
+                        script: %w[spinach],
+                        image: { name: 'ruby:2.7' },
+                        services: [{ name: 'postgres:9.1' }, { name: 'mysql:5.5' }],
+                        stage: 'test',
+                        cache: [{ key: 'k', untracked: true, paths: ['public/'], policy: 'pull-push', when: 'on_success' }],
+                        variables: { 'VAR' => 'job' },
+                        ignore: false,
+                        after_script: ['make clean'],
+                        only: { refs: %w[branches tags] },
+                        scheduling_type: :stage }
+            )
+          end
+        end
+      end
+    end
+
     context 'when most of entires not defined' do
       before do
         root.compose!
@@ -263,12 +365,25 @@ RSpec.describe Gitlab::Ci::Config::Entry::Root do
         end
       end
 
+      describe '#cache_value' do
+        it 'returns correct cache definition' do
+          expect(root.cache_value).to eq([key: 'a', policy: 'pull-push', when: 'on_success'])
+        end
+      end
+
+      context 'with multiple_cache_per_job FF disabled' do
+        before do
+          stub_feature_flags(multiple_cache_per_job: false)
+          root.compose!
+        end
+
         describe '#cache_value' do
           it 'returns correct cache definition' do
             expect(root.cache_value).to eq(key: 'a', policy: 'pull-push', when: 'on_success')
           end
         end
       end
+    end
 
     context 'when variables resembles script-type job' do
       before do

spec/lib/gitlab/ci/pipeline/seed/build/cache_spec.rb

@@ -9,6 +9,11 @@ RSpec.describe Gitlab::Ci::Pipeline::Seed::Build::Cache do
 
   let(:processor) { described_class.new(pipeline, config) }
 
+  context 'with multiple_cache_per_job ff disabled' do
+    before do
+      stub_feature_flags(multiple_cache_per_job: false)
+    end
+
     describe '#build_attributes' do
       subject { processor.build_attributes }
 
@@ -249,4 +254,220 @@ RSpec.describe Gitlab::Ci::Pipeline::Seed::Build::Cache do
         it { is_expected.to include(options: {}) }
       end
     end
+  end
+
+  describe '#attributes' do
+    subject { processor.attributes }
+
+    context 'with cache:key' do
+      let(:config) do
+        {
+          key: 'a-key',
+          paths: ['vendor/ruby']
+        }
+      end
+
+      it { is_expected.to include(config) }
+    end
+
+    context 'with cache:key as a symbol' do
+      let(:config) do
+        {
+          key: :a_key,
+          paths: ['vendor/ruby']
+        }
+      end
+
+      it { is_expected.to include(config.merge(key: "a_key")) }
+    end
+
+    context 'with cache:key:files' do
+      shared_examples 'default key' do
+        let(:config) do
+          { key: { files: files } }
+        end
+
+        it 'uses default key' do
+          expected = { key: 'default' }
+
+          is_expected.to include(expected)
+        end
+      end
+
+      shared_examples 'version and gemfile files' do
+        let(:config) do
+          {
+            key: {
+              files: files
+            },
+            paths: ['vendor/ruby']
+          }
+        end
+
+        it 'builds a string key' do
+          expected = {
+                key: '703ecc8fef1635427a1f86a8a1a308831c122392',
+                paths: ['vendor/ruby']
+            }
+
+          is_expected.to include(expected)
+        end
+      end
+
+      context 'with existing files' do
+        let(:files) { ['VERSION', 'Gemfile.zip'] }
+
+        it_behaves_like 'version and gemfile files'
+      end
+
+      context 'with files starting with ./' do
+        let(:files) { ['Gemfile.zip', './VERSION'] }
+
+        it_behaves_like 'version and gemfile files'
+      end
+
+      context 'with files ending with /' do
+        let(:files) { ['Gemfile.zip/'] }
+
+        it_behaves_like 'default key'
+      end
+
+      context 'with new line in filenames' do
+        let(:files) { ["Gemfile.zip\nVERSION"] }
+
+        it_behaves_like 'default key'
+      end
+
+      context 'with missing files' do
+        let(:files) { ['project-gemfile.lock', ''] }
+
+        it_behaves_like 'default key'
+      end
+
+      context 'with directories' do
+        shared_examples 'foo/bar directory key' do
+          let(:config) do
+            {
+              key: {
+                files: files
+              }
+            }
+          end
+
+          it 'builds a string key' do
+            expected = { key: '74bf43fb1090f161bdd4e265802775dbda2f03d1' }
+
+            is_expected.to include(expected)
+          end
+        end
+
+        context 'with directory' do
+          let(:files) { ['foo/bar'] }
+
+          it_behaves_like 'foo/bar directory key'
+        end
+
+        context 'with directory ending in slash' do
+          let(:files) { ['foo/bar/'] }
+
+          it_behaves_like 'foo/bar directory key'
+        end
+
+        context 'with directories ending in slash star' do
+          let(:files) { ['foo/bar/*'] }
+
+          it_behaves_like 'foo/bar directory key'
+        end
+      end
+    end
+
+    context 'with cache:key:prefix' do
+      context 'without files' do
+        let(:config) do
+          {
+            key: {
+              prefix: 'a-prefix'
+            },
+            paths: ['vendor/ruby']
+          }
+        end
+
+        it 'adds prefix to default key' do
+          expected = {
+                key: 'a-prefix-default',
+                paths: ['vendor/ruby']
+              }
+
+          is_expected.to include(expected)
+        end
+      end
+
+      context 'with existing files' do
+        let(:config) do
+          {
+            key: {
+              files: ['VERSION', 'Gemfile.zip'],
+              prefix: 'a-prefix'
+            },
+            paths: ['vendor/ruby']
+          }
+        end
+
+        it 'adds prefix key' do
+          expected = {
+                key: 'a-prefix-703ecc8fef1635427a1f86a8a1a308831c122392',
+                paths: ['vendor/ruby']
+              }
+
+          is_expected.to include(expected)
+        end
+      end
+
+      context 'with missing files' do
+        let(:config) do
+          {
+            key: {
+              files: ['project-gemfile.lock', ''],
+              prefix: 'a-prefix'
+            },
+            paths: ['vendor/ruby']
+          }
+        end
+
+        it 'adds prefix to default key' do
+          expected = {
+                key: 'a-prefix-default',
+                paths: ['vendor/ruby']
+              }
+
+          is_expected.to include(expected)
+        end
+      end
+    end
+
+    context 'with all cache option keys' do
+      let(:config) do
+        {
+          key: 'a-key',
+          paths: ['vendor/ruby'],
+          untracked: true,
+          policy: 'push',
+          when: 'on_success'
+        }
+      end
+
+      it { is_expected.to include(config) }
+    end
+
+    context 'with unknown cache option keys' do
+      let(:config) do
+        {
+          key: 'a-key',
+          unknown_key: true
+        }
+      end
+
+      it { expect { subject }.to raise_error(ArgumentError, /unknown_key/) }
+    end
+  end
 end

spec/lib/gitlab/ci/pipeline/seed/build_spec.rb

@@ -87,6 +87,11 @@ RSpec.describe Gitlab::Ci::Pipeline::Seed::Build do
       end
     end
 
+    context 'with multiple_cache_per_job FF disabled' do
+      before do
+        stub_feature_flags(multiple_cache_per_job: false)
+      end
+
       context 'with cache:key' do
         let(:attributes) do
           {
@@ -117,9 +122,7 @@ RSpec.describe Gitlab::Ci::Pipeline::Seed::Build do
         it 'includes cache options' do
           cache_options = {
             options: {
-            cache: {
-              key: 'f155568ad0933d8358f66b846133614f76dd0ca4'
-            }
+              cache: { key: 'f155568ad0933d8358f66b846133614f76dd0ca4' }
             }
           }
 
@@ -160,9 +163,45 @@ RSpec.describe Gitlab::Ci::Pipeline::Seed::Build do
         it 'includes cache options' do
           cache_options = {
             options: {
-            cache: {
-              key: 'something-f155568ad0933d8358f66b846133614f76dd0ca4'
+              cache: { key: 'something-f155568ad0933d8358f66b846133614f76dd0ca4' }
+            }
           }
+
+          is_expected.to include(cache_options)
+        end
+      end
+    end
+
+    context 'with cache:key' do
+      let(:attributes) do
+        {
+          name: 'rspec',
+          ref: 'master',
+          cache: [{
+            key: 'a-value'
+          }]
+        }
+      end
+
+      it { is_expected.to include(options: { cache: [a_hash_including(key: 'a-value')] }) }
+
+      context 'with cache:key:files' do
+        let(:attributes) do
+          {
+            name: 'rspec',
+            ref: 'master',
+            cache: [{
+              key: {
+                files: ['VERSION']
+              }
+            }]
+          }
+        end
+
+        it 'includes cache options' do
+          cache_options = {
+            options: {
+              cache: [a_hash_including(key: 'f155568ad0933d8358f66b846133614f76dd0ca4')]
             }
           }
 
@@ -170,6 +209,48 @@ RSpec.describe Gitlab::Ci::Pipeline::Seed::Build do
         end
       end
 
+      context 'with cache:key:prefix' do
+        let(:attributes) do
+          {
+            name: 'rspec',
+            ref: 'master',
+            cache: [{
+              key: {
+                prefix: 'something'
+              }
+            }]
+          }
+        end
+
+        it { is_expected.to include(options: { cache: [a_hash_including( key: 'something-default' )] }) }
+      end
+
+      context 'with cache:key:files and prefix' do
+        let(:attributes) do
+          {
+            name: 'rspec',
+            ref: 'master',
+            cache: [{
+              key: {
+                files: ['VERSION'],
+                prefix: 'something'
+              }
+            }]
+          }
+        end
+
+        it 'includes cache options' do
+          cache_options = {
+            options: {
+              cache: [a_hash_including(key: 'something-f155568ad0933d8358f66b846133614f76dd0ca4')]
+            }
+          }
+
+          is_expected.to include(cache_options)
+        end
+      end
+    end
+
     context 'with empty cache' do
       let(:attributes) do
         {
@@ -179,7 +260,7 @@ RSpec.describe Gitlab::Ci::Pipeline::Seed::Build do
         }
       end
 
-      it { is_expected.to include(options: {}) }
+      it { is_expected.to include({}) }
     end
 
     context 'with allow_failure' do
@@ -296,7 +377,7 @@ RSpec.describe Gitlab::Ci::Pipeline::Seed::Build do
         it 'does not have environment' do
           expect(subject).not_to be_has_environment
           expect(subject.environment).to be_nil
-          expect(subject.metadata.expanded_environment_name).to be_nil
+          expect(subject.metadata).to be_nil
           expect(Environment.exists?(name: expected_environment_name)).to eq(false)
         end
       end

spec/lib/gitlab/ci/yaml_processor_spec.rb

@@ -1368,6 +1368,10 @@ module Gitlab
         end
       end
 
+      context 'with multiple_cache_per_job FF disabled' do
+        before do
+          stub_feature_flags(multiple_cache_per_job: false)
+        end
         describe 'cache' do
           context 'when cache definition has unknown keys' do
             let(:config) do
@@ -1511,6 +1515,165 @@ module Gitlab
             )
           end
         end
+      end
+
+      describe 'cache' do
+        context 'when cache definition has unknown keys' do
+          let(:config) do
+            YAML.dump(
+              { cache: { untracked: true, invalid: 'key' },
+                rspec: { script: 'rspec' } })
+          end
+
+          it_behaves_like 'returns errors', 'cache config contains unknown keys: invalid'
+        end
+
+        it "returns cache when defined globally" do
+          config = YAML.dump({
+                              cache: { paths: ["logs/", "binaries/"], untracked: true, key: 'key' },
+                              rspec: {
+                                script: "rspec"
+                              }
+                            })
+
+          config_processor = Gitlab::Ci::YamlProcessor.new(config).execute
+
+          expect(config_processor.stage_builds_attributes("test").size).to eq(1)
+          expect(config_processor.stage_builds_attributes("test").first[:cache]).to eq([
+            paths: ["logs/", "binaries/"],
+            untracked: true,
+            key: 'key',
+            policy: 'pull-push',
+            when: 'on_success'
+          ])
+        end
+
+        it "returns cache when defined in default context" do
+          config = YAML.dump(
+            {
+              default: {
+                cache: { paths: ["logs/", "binaries/"], untracked: true, key: { files: ['file'] } }
+              },
+              rspec: {
+                script: "rspec"
+              }
+            })
+
+          config_processor = Gitlab::Ci::YamlProcessor.new(config).execute
+
+          expect(config_processor.stage_builds_attributes("test").size).to eq(1)
+          expect(config_processor.stage_builds_attributes("test").first[:cache]).to eq([
+            paths: ["logs/", "binaries/"],
+            untracked: true,
+            key: { files: ['file'] },
+            policy: 'pull-push',
+            when: 'on_success'
+          ])
+        end
+
+        it 'returns cache key/s when defined in a job' do
+          config = YAML.dump({
+                              rspec: {
+                                cache: [
+                                  { paths: ['binaries/'], untracked: true, key: 'keya' },
+                                  { paths: ['logs/', 'binaries/'], untracked: true, key: 'key' }
+                                  ],
+                                script: 'rspec'
+                              }
+                            })
+
+          config_processor = Gitlab::Ci::YamlProcessor.new(config).execute
+
+          expect(config_processor.stage_builds_attributes('test').size).to eq(1)
+          expect(config_processor.stage_builds_attributes('test').first[:cache]).to eq(
+            [
+              {
+                paths: ['binaries/'],
+                untracked: true,
+                key: 'keya',
+                policy: 'pull-push',
+                when: 'on_success'
+              },
+              {
+                paths: ['logs/', 'binaries/'],
+                untracked: true,
+                key: 'key',
+                policy: 'pull-push',
+                when: 'on_success'
+              }
+            ]
+          )
+        end
+
+        it 'returns cache files' do
+          config = YAML.dump(
+            rspec: {
+              cache: {
+                  paths: ['binaries/'],
+                  untracked: true,
+                  key: { files: ['file'] }
+                },
+              script: 'rspec'
+            }
+          )
+
+          config_processor = Gitlab::Ci::YamlProcessor.new(config).execute
+
+          expect(config_processor.stage_builds_attributes('test').size).to eq(1)
+          expect(config_processor.stage_builds_attributes('test').first[:cache]).to eq([
+            paths: ['binaries/'],
+            untracked: true,
+            key: { files: ['file'] },
+            policy: 'pull-push',
+            when: 'on_success'
+          ])
+        end
+
+        it 'returns cache files with prefix' do
+          config = YAML.dump(
+            rspec: {
+              cache: {
+                paths: ['logs/', 'binaries/'],
+                untracked: true,
+                key: { files: ['file'], prefix: 'prefix' }
+              },
+              script: 'rspec'
+            }
+          )
+
+          config_processor = Gitlab::Ci::YamlProcessor.new(config).execute
+
+          expect(config_processor.stage_builds_attributes('test').size).to eq(1)
+          expect(config_processor.stage_builds_attributes('test').first[:cache]).to eq([
+            paths: ['logs/', 'binaries/'],
+            untracked: true,
+            key: { files: ['file'], prefix: 'prefix' },
+            policy: 'pull-push',
+            when: 'on_success'
+          ])
+        end
+
+        it "overwrite cache when defined for a job and globally" do
+          config = YAML.dump({
+                              cache: { paths: ["logs/", "binaries/"], untracked: true, key: 'global' },
+                              rspec: {
+                                script: "rspec",
+                                cache: { paths: ["test/"], untracked: false, key: 'local' }
+                              }
+                            })
+
+          config_processor = Gitlab::Ci::YamlProcessor.new(config).execute
+
+          expect(config_processor.stage_builds_attributes("test").size).to eq(1)
+          expect(config_processor.stage_builds_attributes("test").first[:cache]).to eq([
+            paths: ["test/"],
+            untracked: false,
+            key: 'local',
+            policy: 'pull-push',
+            when: 'on_success'
+          ])
+        end
+      end
 
       describe "Artifacts" do
         it "returns artifacts when defined" do

spec/models/ci/build_spec.rb

@@ -817,6 +817,14 @@ RSpec.describe Ci::Build do
   end
 
   describe '#cache' do
+    let(:options) do
+      { cache: [{ key: "key", paths: ["public"], policy: "pull-push" }] }
+    end
+
+    context 'with multiple_cache_per_job FF disabled' do
+      before do
+        stub_feature_flags(multiple_cache_per_job: false)
+      end
       let(:options) { { cache: { key: "key", paths: ["public"], policy: "pull-push" } } }
 
       subject { build.cache }
@@ -848,7 +856,55 @@ RSpec.describe Ci::Build do
           allow(build).to receive(:options).and_return({})
         end
 
-      it { is_expected.to eq([nil]) }
+        it { is_expected.to eq([]) }
+      end
+    end
+
+    subject { build.cache }
+
+    context 'when build has cache' do
+      before do
+        allow(build).to receive(:options).and_return(options)
+      end
+
+      context 'when build has multiple caches' do
+        let(:options) do
+          { cache: [
+            { key: "key", paths: ["public"], policy: "pull-push" },
+            { key: "key2", paths: ["public"], policy: "pull-push" }
+          ] }
+        end
+
+        before do
+          allow_any_instance_of(Project).to receive(:jobs_cache_index).and_return(1)
+        end
+
+        it { is_expected.to match([a_hash_including(key: "key-1"), a_hash_including(key: "key2-1")]) }
+      end
+
+      context 'when project has jobs_cache_index' do
+        before do
+          allow_any_instance_of(Project).to receive(:jobs_cache_index).and_return(1)
+        end
+
+        it { is_expected.to be_an(Array).and all(include(key: "key-1")) }
+      end
+
+      context 'when project does not have jobs_cache_index' do
+        before do
+          allow_any_instance_of(Project).to receive(:jobs_cache_index).and_return(nil)
+        end
+
+        it { is_expected.to eq(options[:cache]) }
+      end
+    end
+
+    context 'when build does not have cache' do
+      before do
+        allow(build).to receive(:options).and_return({})
+      end
+
+      it { is_expected.to be_empty }
     end
   end