Add tests and documentation about how CI "extends" can be excluded

doc/ci/yaml/index.md

@@ -1078,6 +1078,61 @@ In this example:
 - `script` does not merge, but `script: ['rake rspec']` overwrites
   `script: ['echo "Hello world!"']`. You can use [YAML anchors](#anchors) to merge arrays.
 
+##### Exclude a key from `extends`
+
+To exclude a key from the extended content, you must assign it to `null`, for example:
+
+```yaml
+.base:
+  script: test
+  variables:
+    VAR1: base var 1
+
+test1:
+  extends: .base
+  variables:
+    VAR1: test1 var 1
+    VAR2: test2 var 2
+
+test2:
+  extends: .base
+  variables:
+    VAR2: test2 var 2
+
+test3:
+  extends: .base
+  variables: {}
+
+test4:
+  extends: .base
+  variables: null
+```
+
+Merged configuration:
+
+```yaml
+test1:
+  script: test
+  variables:
+    VAR1: test1 var 1
+    VAR2: test2 var 2
+
+test2:
+  script: test
+  variables:
+    VAR1: base var 1
+    VAR2: test2 var 2
+
+test3:
+  script: test
+  variables:
+    VAR1: base var 1
+
+test4:
+  script: test
+  variables: null
+```
+
 #### Use `extends` and `include` together
 
 To reuse configuration from different configuration files,

spec/lib/gitlab/ci/config/extendable_spec.rb

@@ -73,6 +73,50 @@ RSpec.describe Gitlab::Ci::Config::Extendable do
       end
     end
 
+    context 'when the job tries to delete an extension key' do
+      let(:hash) do
+        {
+          something: {
+            script: 'deploy',
+            only: { variables: %w[$SOMETHING] }
+          },
+
+          test1: {
+            extends: 'something',
+            script: 'ls',
+            only: {}
+          },
+
+          test2: {
+            extends: 'something',
+            script: 'ls',
+            only: nil
+          }
+        }
+      end
+
+      it 'deletes the key if assigned to null' do
+        expect(subject.to_hash).to eq(
+          something: {
+            script: 'deploy',
+            only: { variables: %w[$SOMETHING] }
+          },
+          test1: {
+            extends: 'something',
+            script: 'ls',
+            only: {
+              variables: %w[$SOMETHING]
+            }
+          },
+          test2: {
+            extends: 'something',
+            script: 'ls',
+            only: nil
+          }
+        )
+      end
+    end
+
     context 'when a hash uses recursive extensions' do
       let(:hash) do
         {

spec/lib/gitlab/ci/yaml_processor_spec.rb

@@ -1046,6 +1046,64 @@ module Gitlab
           end
         end
 
+        context 'when overriding `extends`' do
+          let(:config) do
+            <<~YAML
+              .base:
+                script: test
+                variables:
+                  VAR1: base var 1
+
+              test1:
+                extends: .base
+                variables:
+                  VAR1: test1 var 1
+                  VAR2: test2 var 2
+
+              test2:
+                extends: .base
+                variables:
+                  VAR2: test2 var 2
+
+              test3:
+                extends: .base
+                variables: {}
+
+              test4:
+                extends: .base
+                variables: null
+            YAML
+          end
+
+          it 'correctly extends jobs' do
+            expect(config_processor.builds[0]).to include(
+              name: 'test1',
+              options: { script: ['test'] },
+              job_variables: [{ key: 'VAR1', value: 'test1 var 1', public: true },
+                              { key: 'VAR2', value: 'test2 var 2', public: true }]
+            )
+
+            expect(config_processor.builds[1]).to include(
+              name: 'test2',
+              options: { script: ['test'] },
+              job_variables: [{ key: 'VAR1', value: 'base var 1', public: true },
+                              { key: 'VAR2', value: 'test2 var 2', public: true }]
+            )
+
+            expect(config_processor.builds[2]).to include(
+              name: 'test3',
+              options: { script: ['test'] },
+              job_variables: [{ key: 'VAR1', value: 'base var 1', public: true }]
+            )
+
+            expect(config_processor.builds[3]).to include(
+              name: 'test4',
+              options: { script: ['test'] },
+              job_variables: []
+            )
+          end
+        end
+
         context 'when using recursive `extends`' do
           let(:config) do
             <<~YAML