Executes a validation before the job to ensure that a branch called dependabot does not exist

If a branch named `dependabot` already exists, branches in the format `dependabot/<name>` cannot be created because Git does not allow a ref to be both a file and a directory

Fixes #14193

Author: yeikel

common/lib/dependabot/errors.rb

@@ -52,6 +52,13 @@ def self.fetcher_error_details(error)
           message: error.message
         }
       }
+    when Dependabot::RefNamespaceConflictError
+      {
+        "error-type": "file_fetcher_error",
+        "error-detail": {
+          message: error.message
+        }
+      }
     when Dependabot::DirectoryNotFound
       {
         "error-type": "directory_not_found",
@@ -469,6 +476,8 @@ class NotImplemented < DependabotError; end
 
   class InvalidGitAuthToken < DependabotError; end
 
+  class RefNamespaceConflictError < DependabotError; end
+
   #####################
   # Repo level errors #
   #####################

updater/lib/dependabot/file_fetcher_command.rb

@@ -31,6 +31,7 @@ def perform_job # rubocop:disable Metrics/AbcSize
         begin
           connectivity_check if ENV["ENABLE_CONNECTIVITY_CHECK"] == "1"
           validate_target_branch
+          dependabot_ref_namespace_available?
           clone_repo_contents
           @base_commit_sha = file_fetcher.commit
           raise "base commit SHA not found" unless @base_commit_sha
@@ -211,6 +212,26 @@ def with_retries(max_retries: 2, &_block)
       end
     end
 
+    # Validates that the repository does not have a top-level branch named `dependabot`.
+    sig { void }
+    def dependabot_ref_namespace_available?
+      dependabot_branch = "dependabot"
+      begin
+        branch_exists = git_metadata_fetcher.ref_names.include?(dependabot_branch)
+        if branch_exists
+          error_message = "Branch '#{dependabot_branch}' already exists and causes a Git ref namespace conflict. " \
+                          "Git can’t create `dependabot/...` branches while the branch `dependabot` exists." \
+                          "Please delete the '#{dependabot_branch}' branch and retry."
+          raise Dependabot::RefNamespaceConflictError, error_message
+        end
+      rescue Dependabot::RefNamespaceConflictError
+        # Re-raise so they aren't caught by the generic rescue
+        raise
+      rescue StandardError => e
+        Dependabot.logger.warn("Could not validate the existence of the 'dependabot' branch: #{e.message}")
+      end
+    end
+
     sig { void }
     def validate_target_branch
       return unless job.source.branch

updater/spec/dependabot/file_fetcher_command_spec.rb

@@ -264,7 +264,11 @@
 
       it "falls back to existing validation and continues processing" do
         # Should not raise error during early validation, but log warning
-        expect(Dependabot.logger).to receive(:warn).with(/Could not validate target branch early:/)
+        expect(Dependabot.logger).to receive(:warn)
+          .with(/Could not validate target branch early:/).ordered
+
+        expect(Dependabot.logger).to receive(:warn)
+          .with(/Could not validate the existence of the 'dependabot' branch/).ordered
 
         expect { perform_job }.not_to raise_error
       end
@@ -309,6 +313,42 @@
       end
     end
 
+    context "when the dependabot branch exists" do
+      let(:job_definition) do
+        job_def = JSON.parse(fixture("jobs/job_with_credentials.json"))
+        job_def
+      end
+
+      let(:git_metadata_fetcher) { double("GitMetadataFetcher") }
+
+      before do
+        allow_any_instance_of(described_class)
+          .to receive(:git_metadata_fetcher)
+          .and_return(git_metadata_fetcher)
+
+        allow(git_metadata_fetcher).to receive_messages(
+          ref_names: %w(main develop dependabot),
+          upload_pack: nil
+        )
+      end
+
+      it "raises error with helpful message before file operations" do
+        expect(api_client)
+          .to receive(:record_update_job_error)
+          .with(
+            error_details: {
+              message: "Branch 'dependabot' already exists and causes a Git ref namespace conflict. " \
+                       "Git can’t create `dependabot/...` branches while the branch `dependabot` exists." \
+                       "Please delete the 'dependabot' branch and retry."
+            },
+            error_type: "file_fetcher_error"
+          )
+        expect(api_client).to receive(:mark_job_as_processed)
+
+        expect { perform_job }.to output(/Error during file fetching; aborting/).to_stdout_from_any_process
+      end
+    end
+
     context "when the fetcher raises a RepoNotFound error" do
       let(:provider) { job_definition.dig("job", "source", "provider") }
       let(:repo) { job_definition.dig("job", "source", "repo") }