Support refname in external repo CI configuration

Gitlab now supports specifying a refname when setting the CI/CD
configuration file to an external repo with:

.gitlab-ci.yml@mygroup/another-project:refname

Changelog: added

doc/ci/pipelines/settings.md

@@ -124,7 +124,7 @@ If the CI/CD configuration file is on an external site, the URL must end with `.
 
 If the CI/CD configuration file is in a different project:
 
-- The file must exist on its default branch.
+- The file must exist on its default branch, or specify the branch as refname.
 - The path must be relative to the root directory in the other project.
 - The path must include the group and project name at the end.
 
@@ -132,6 +132,7 @@ For example:
 
 - `.gitlab-ci.yml@mygroup/another-project`
 - `my/path/.my-custom-file.yml@mygroup/another-project`
+- `my/path/.my-custom-file.yml@mygroup/another-project:refname`
 
 If the configuration file is in a separate project, you can more set more granular permissions. For example:
 

lib/gitlab/ci/pipeline/chain/config/content/external_project.rb

@@ -11,8 +11,12 @@ module Gitlab
                 strong_memoize(:content) do
                   next unless external_project_path?
 
-                  path_file, path_project = ci_config_path.split('@', 2)
-                  YAML.dump('include' => [{ 'project' => path_project, 'file' => path_file }])
+                  path_file, path_project, ref = extract_location_tokens
+
+                  config_location = { 'project' => path_project, 'file' => path_file }
+                  config_location['ref'] = ref if ref.present?
+
+                  YAML.dump('include' => [config_location])
                 end
               end
 
@@ -26,6 +30,18 @@ module Gitlab
               def external_project_path?
                 ci_config_path =~ /\A.+(yml|yaml)@.+\z/
               end
+
+              # Example: path/to/.gitlab-ci.yml@another-group/another-project:refname
+              def extract_location_tokens
+                path_file, path_project = ci_config_path.split('@', 2)
+
+                if path_project.include? ":"
+                  project, ref = path_project.split(':', 2)
+                  [path_file, project, ref]
+                else
+                  [path_file, path_project]
+                end
+              end
             end
           end
         end

spec/lib/gitlab/ci/pipeline/chain/config/content_spec.rb

@@ -92,6 +92,27 @@ RSpec.describe Gitlab::Ci::Pipeline::Chain::Config::Content do
         expect(pipeline.pipeline_config.content).to eq(config_content_result)
         expect(command.config_content).to eq(config_content_result)
       end
+
+      context 'when path specifies a refname' do
+        let(:ci_config_path) { 'path/to/.gitlab-ci.yml@another-group/another-repo:refname' }
+        let(:config_content_result) do
+          <<~EOY
+            ---
+            include:
+            - project: another-group/another-repo
+              file: path/to/.gitlab-ci.yml
+              ref: refname
+          EOY
+        end
+
+        it 'builds root config including the path and refname to another repository' do
+          subject.perform!
+
+          expect(pipeline.config_source).to eq 'external_project_source'
+          expect(pipeline.pipeline_config.content).to eq(config_content_result)
+          expect(command.config_content).to eq(config_content_result)
+        end
+      end
     end
 
     context 'when config is defined in the default .gitlab-ci.yml' do