ci(config): validate 'include' keyword

During `.gitlab-ci.yml` configuration file validation there are two
cases:
1- either we are validating a file within a project context (a project
and a sha is given in option parameters)
2- either we are validating a file with no project context (as in the
api POST /ci/lint)

In the first case, all `include:` keywords are replaced by the content
of the included CI cnfiguration files.

In the second case, the `include:` configuration is kept untouched.

The current problem arises in the second case when one wants to
validate a generic gitlab-ci configuration file with an `include:`
keyword from the API. The following error will be raised by the API:
`"jobs:include config should be a hash"`.

This commit fixes the behavior by validating the `include:` keyword if
its present to not parse it as a job definition.

Fixes #55863 / #52822

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

@@ -17,6 +17,9 @@ module Gitlab
           entry :image, Entry::Image,
             description: 'Docker image that will be used to execute jobs.'
 
+          entry :include, Entry::Includes,
+                description: 'List of external YAML files to include.'
+
           entry :services, Entry::Services,
             description: 'Docker images that will be linked to the container.'
 

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

+# frozen_string_literal: true
+
+module Gitlab
+  module Ci
+    class Config
+      module Entry
+        ##
+        # Entry that represents a single include.
+        #
+        class Include < ::Gitlab::Config::Entry::Node
+          include ::Gitlab::Config::Entry::Validatable
+
+          ALLOWED_KEYS = %i[local file remote template].freeze
+
+          validations do
+            validates :config, hash_or_string: true
+            validates :config, allowed_keys: ALLOWED_KEYS
+          end
+        end
+      end
+    end
+  end
+end

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

+# frozen_string_literal: true
+
+module Gitlab
+  module Ci
+    class Config
+      module Entry
+        ##
+        # Entry that represents a list of include.
+        #
+        class Includes < ::Gitlab::Config::Entry::Node
+          include ::Gitlab::Config::Entry::Validatable
+
+          validations do
+            validates :config, type: Array
+          end
+
+          def self.aspects
+            super.append -> do
+              @config = Array.wrap(@config)
+
+              @config.each_with_index do |config, i|
+                @entries[i] = ::Gitlab::Config::Entry::Factory.new(Entry::Include)
+                                .value(config || {})
+                                .create!
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end