[#92] Added --fail-on-missing-branch flag.

AlexSkrypnyk · AlexSkrypnyk · commit a3262b54fb4a · 2025-11-17T17:59:46.000+11:00
Closes #92
diff --git a/phpstan.neon b/phpstan.neon
@@ -13,6 +13,7 @@ parameters:
   excludePaths:
     - vendor/*
     - node_modules/*
+    - tests/Unit/Traits/FilesystemTraitTestClass.php
 
   ignoreErrors:
     -
diff --git a/src/Commands/ArtifactCommand.php b/src/Commands/ArtifactCommand.php
@@ -5,6 +5,7 @@
 namespace DrevOps\GitArtifact\Commands;
 
 use CzProject\GitPhp\GitException;
+use DrevOps\GitArtifact\Exception\BranchNotFoundException;
 use DrevOps\GitArtifact\Git\ArtifactGitRepository;
 use DrevOps\GitArtifact\Traits\FilesystemTrait;
 use DrevOps\GitArtifact\Traits\LoggerTrait;
@@ -105,6 +106,19 @@ class ArtifactCommand extends Command {
    */
   protected bool $showChanges = FALSE;
 
+  /**
+   * Flag to fail deployment when branch is missing.
+   *
+   * By default (false), deployment is skipped with exit code 0.
+   * When true, deployment fails with exit code 1.
+   */
+  protected bool $failOnMissingBranch = FALSE;
+
+  /**
+   * Flag indicating deployment was skipped due to missing branch.
+   */
+  protected bool $deploymentSkipped = FALSE;
+
   /**
    * Flag to specify if push was successful.
    */
@@ -150,17 +164,18 @@ protected function configure(): void {
     // phpcs:disable Generic.Functions.FunctionCallArgumentSpacing.TooMuchSpaceAfterComma
     // phpcs:disable Drupal.WhiteSpace.Comma.TooManySpaces
     $this
-      ->addOption('branch',       NULL, InputOption::VALUE_REQUIRED, 'Destination branch with optional tokens.',                                                    '[branch]')
-      ->addOption('dry-run',      NULL, InputOption::VALUE_NONE,     'Run without pushing to the remote repository.')
-      ->addOption('gitignore',    NULL, InputOption::VALUE_REQUIRED, 'Path to gitignore file to replace current .gitignore. Leave empty to use current .gitignore.')
-      ->addOption('message',      NULL, InputOption::VALUE_REQUIRED, 'Commit message with optional tokens.',                                                        'Deployment commit')
-      ->addOption('mode',         NULL, InputOption::VALUE_REQUIRED, 'Mode of artifact build: branch, force-push. Defaults to force-push.',                         static::MODE_FORCE_PUSH)
-      ->addOption('no-cleanup',   NULL, InputOption::VALUE_NONE,     'Do not cleanup after run.')
-      ->addOption('now',          NULL, InputOption::VALUE_REQUIRED, 'Internal value used to set internal time.')
-      ->addOption('log',          NULL, InputOption::VALUE_REQUIRED, 'Path to the log file.')
-      ->addOption('root',         NULL, InputOption::VALUE_REQUIRED, 'Path to the root for file path resolution. If not specified, current directory is used.')
-      ->addOption('show-changes', NULL, InputOption::VALUE_NONE,     'Show changes made to the repo by the build in the output.')
-      ->addOption('src',          NULL, InputOption::VALUE_REQUIRED, 'Directory where source repository is located. If not specified, root directory is used.');
+      ->addOption('branch',                 NULL, InputOption::VALUE_REQUIRED, 'Destination branch with optional tokens.', '[branch]')
+      ->addOption('dry-run',                NULL, InputOption::VALUE_NONE,     'Run without pushing to the remote repository.')
+      ->addOption('gitignore',              NULL, InputOption::VALUE_REQUIRED, 'Path to gitignore file to replace current .gitignore. Leave empty to use current .gitignore.')
+      ->addOption('message',                NULL, InputOption::VALUE_REQUIRED, 'Commit message with optional tokens.', 'Deployment commit')
+      ->addOption('mode',                   NULL, InputOption::VALUE_REQUIRED, 'Mode of artifact build: branch, force-push. Defaults to force-push.', static::MODE_FORCE_PUSH)
+      ->addOption('no-cleanup',             NULL, InputOption::VALUE_NONE,     'Do not cleanup after run.')
+      ->addOption('now',                    NULL, InputOption::VALUE_REQUIRED, 'Internal value used to set internal time.')
+      ->addOption('log',                    NULL, InputOption::VALUE_REQUIRED, 'Path to the log file.')
+      ->addOption('root',                   NULL, InputOption::VALUE_REQUIRED, 'Path to the root for file path resolution. If not specified, current directory is used.')
+      ->addOption('show-changes',           NULL, InputOption::VALUE_NONE,     'Show changes made to the repo by the build in the output.')
+      ->addOption('src',                    NULL, InputOption::VALUE_REQUIRED, 'Directory where source repository is located. If not specified, root directory is used.')
+      ->addOption('fail-on-missing-branch', NULL, InputOption::VALUE_NONE,     'Fail deployment if source branch cannot be determined. By default, deployment is skipped gracefully.');
     // @formatter:on
     // phpcs:enable Generic.Functions.FunctionCallArgumentSpacing.TooMuchSpaceAfterComma
     // phpcs:enable Drupal.WhiteSpace.Comma.TooManySpaces
@@ -194,6 +209,11 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
       $this->resolveOptions($remote, $input->getOptions());
 
+      // Check if deployment was skipped due to missing branch.
+      if ($this->deploymentSkipped) {
+        return Command::SUCCESS;
+      }
+
       $this->doExecute();
     }
     catch (\Exception $exception) {
@@ -317,6 +337,7 @@ protected function resolveOptions(string $url, array $options): void {
     $this->showChanges = !empty($options['show-changes']);
     $this->needCleanup = empty($options['no-cleanup']);
     $this->isDryRun = !empty($options['dry-run']);
+    $this->failOnMissingBranch = !empty($options['fail-on-missing-branch']);
     $this->logFile = empty($options['log']) ? '' : $this->fsGetAbsolutePath($options['log']);
 
     $this->setMode($options['mode'], $options);
@@ -327,7 +348,28 @@ protected function resolveOptions(string $url, array $options): void {
     $this->repo = new ArtifactGitRepository($this->sourceDir, NULL, $this->logger);
 
     // Set original, destination, artifact branch names.
-    $this->originalBranch = $this->repo->getOriginalBranch();
+    try {
+      $this->originalBranch = $this->repo->getOriginalBranch();
+    }
+    catch (BranchNotFoundException $exception) {
+      if ($this->failOnMissingBranch) {
+        // Strict mode: fail deployment.
+        throw new \RuntimeException('Unable to determine source branch. Deployment failed. ' . $exception->getMessage(), $exception->getCode(), $exception);
+      }
+
+      $commit_hash = $exception->getCommitHash();
+      $this->logger->notice('Source branch not found. Deployment will be skipped.');
+      $this->logger->notice('Commit: ' . $commit_hash);
+
+      $this->output->writeln('<comment>Source branch not found. Deployment skipped.</comment>');
+      $this->output->writeln('<comment>Commit: ' . $commit_hash . '</comment>');
+      $this->output->writeln('<info>Use --fail-on-missing-branch to fail deployment instead.</info>');
+
+      // Set flag to skip deployment and return early from execute().
+      $this->deploymentSkipped = TRUE;
+
+      return;
+    }
 
     $branch = $this->tokenProcess($options['branch']);
     if (!ArtifactGitRepository::isValidBranchName($branch)) {
diff --git a/src/Exception/BranchNotFoundException.php b/src/Exception/BranchNotFoundException.php
@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DrevOps\GitArtifact\Exception;
+
+/**
+ * Exception when branch cannot be determined.
+ *
+ * This can occur in two scenarios:
+ * 1. Detached HEAD state with no traceable source branch.
+ * 2. Branch was deleted while CI is still running.
+ */
+class BranchNotFoundException extends GitException {
+
+  /**
+   * Constructor.
+   *
+   * @param string $message
+   *   The exception message.
+   * @param string $commitHash
+   *   The commit hash where the repository is currently at.
+   * @param \Throwable|null $previous
+   *   Previous exception.
+   */
+  public function __construct(
+    string $message = 'Unable to determine source branch',
+    protected string $commitHash = '',
+    ?\Throwable $previous = NULL,
+  ) {
+    parent::__construct($message, 0, $previous);
+  }
+
+  /**
+   * Get the commit hash.
+   *
+   * @return string
+   *   The commit hash.
+   */
+  public function getCommitHash(): string {
+    return $this->commitHash;
+  }
+
+}
diff --git a/src/Exception/GitArtifactException.php b/src/Exception/GitArtifactException.php
@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DrevOps\GitArtifact\Exception;
+
+/**
+ * Base exception for all git-artifact exceptions.
+ */
+class GitArtifactException extends \RuntimeException {
+
+}
diff --git a/src/Exception/GitException.php b/src/Exception/GitException.php
@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DrevOps\GitArtifact\Exception;
+
+/**
+ * Exception for Git-related errors.
+ */
+class GitException extends GitArtifactException {
+
+}
diff --git a/src/Git/ArtifactGitRepository.php b/src/Git/ArtifactGitRepository.php
@@ -8,6 +8,7 @@
 use CzProject\GitPhp\GitRepository;
 use CzProject\GitPhp\IRunner;
 use CzProject\GitPhp\RunnerResult;
+use DrevOps\GitArtifact\Exception\BranchNotFoundException;
 use DrevOps\GitArtifact\Traits\FilesystemTrait;
 use DrevOps\GitArtifact\Traits\LoggerTrait;
 use Psr\Log\LoggerInterface;
@@ -265,7 +266,35 @@ public function getOriginalBranch(): string {
       }
 
       if (empty($branch)) {
-        throw new \Exception('Unable to determine a detachment source');
+        // Get current commit hash.
+        $commit_hash = $this->execute(['rev-parse', 'HEAD'])[0] ?? '';
+
+        throw new BranchNotFoundException(
+          'Unable to determine a detachment source',
+          $commit_hash
+        );
+      }
+
+      // Validate that the extracted value is actually a branch or tag, not just
+      // a commit hash. If it's only a commit hash, we cannot determine the
+      // original branch.
+      try {
+        $this->execute(['show-ref', '--verify', 'refs/heads/' . $branch]);
+      }
+      catch (GitException $e1) {
+        try {
+          $this->execute(['show-ref', '--verify', 'refs/tags/' . $branch]);
+        }
+        catch (GitException $e2) {
+          // Not a branch or tag - just a commit hash.
+          // Get current commit hash.
+          $commit_hash = $this->execute(['rev-parse', 'HEAD'])[0] ?? '';
+
+          throw new BranchNotFoundException(
+            'Unable to determine a detachment source',
+            $commit_hash
+          );
+        }
       }
     }
 
diff --git a/tests/Functional/MissingBranchTest.php b/tests/Functional/MissingBranchTest.php
@@ -0,0 +1,145 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DrevOps\GitArtifact\Tests\Functional;
+
+use CzProject\GitPhp\Git;
+use DrevOps\GitArtifact\Commands\ArtifactCommand;
+use DrevOps\GitArtifact\Git\ArtifactGitRepository;
+use PHPUnit\Framework\Attributes\CoversClass;
+
+#[CoversClass(ArtifactCommand::class)]
+#[CoversClass(ArtifactGitRepository::class)]
+class MissingBranchTest extends FunctionalTestCase {
+
+  /**
+   * Test deployment skips gracefully when branch is missing (default).
+   *
+   * This simulates the scenario where a branch was deleted after PR merge.
+   * Default behavior should skip deployment with exit code 0.
+   */
+  public function testMissingBranchDefaultBehavior(): void {
+    $this->gitCreateFixtureCommits(1);
+
+    // Create an orphaned commit (not on any branch).
+    $repo = (new Git())->open($this->src);
+
+    // Create orphaned branch.
+    $repo->run('checkout', '--orphan', 'orphan-branch');
+
+    // Create a commit on orphan branch.
+    $this->fixtureCreateFile($this->src, 'f_orphan');
+    $repo->addAllChanges();
+    $repo->commit('Orphan commit');
+
+    // Get the commit hash.
+    $commits = $repo->execute(['rev-parse', 'HEAD']);
+    $commit_hash = $commits[0];
+
+    // Switch back to main branch and delete orphan branch.
+    $repo->checkout($this->currentBranch);
+    $repo->run('branch', '-D', 'orphan-branch');
+
+    // Checkout the orphaned commit - now it's truly not on any branch.
+    $repo->checkout($commit_hash);
+
+    // Default behavior: should skip deployment with exit code 0.
+    // Use explicit branch name (no tokens) to avoid token processing issues.
+    $output = $this->runArtifactCommand([
+      '--branch' => 'testbranch',
+      '--dry-run' => TRUE,
+    ]);
+
+    $this->assertStringContainsString('Source branch not found. Deployment skipped.', $output);
+    $this->assertStringContainsString('Commit: ' . $commit_hash, $output);
+    $this->assertStringContainsString('Use --fail-on-missing-branch to fail deployment instead', $output);
+    $this->assertStringNotContainsString('Processing failed with an error:', $output);
+  }
+
+  /**
+   * Test deployment fails when branch is missing with flag.
+   *
+   * With --fail-on-missing-branch flag, deployment should fail.
+   */
+  public function testMissingBranchWithFlag(): void {
+    $this->gitCreateFixtureCommits(1);
+
+    // Create an orphaned commit (not on any branch).
+    $repo = (new Git())->open($this->src);
+
+    // Create orphaned branch.
+    $repo->run('checkout', '--orphan', 'orphan-branch-2');
+
+    // Create a commit on orphan branch.
+    $this->fixtureCreateFile($this->src, 'f_orphan_2');
+    $repo->addAllChanges();
+    $repo->commit('Orphan commit 2');
+
+    // Get the commit hash.
+    $commits = $repo->execute(['rev-parse', 'HEAD']);
+    $commit_hash = $commits[0];
+
+    // Switch back to main branch and delete orphan branch.
+    $repo->checkout($this->currentBranch);
+    $repo->run('branch', '-D', 'orphan-branch-2');
+
+    // Checkout the orphaned commit - now it's truly not on any branch.
+    $repo->checkout($commit_hash);
+
+    // With --fail-on-missing-branch, should fail.
+    // Use explicit branch name (no tokens) to avoid token processing issues.
+    $output = $this->runArtifactCommand([
+      '--branch' => 'testbranch',
+      '--fail-on-missing-branch' => TRUE,
+      '--dry-run' => TRUE,
+    ], TRUE);
+
+    $this->assertStringContainsString('Processing failed with an error:', $output);
+    $this->assertStringContainsString('Unable to determine source branch', $output);
+  }
+
+  /**
+   * Test normal deployment when branch exists.
+   *
+   * Verifies that normal operation still works when branch is available.
+   */
+  public function testNormalDeploymentWithBranch(): void {
+    $this->gitCreateFixtureCommits(1);
+
+    // Normal deployment with existing branch should work.
+    $output = $this->assertArtifactCommandSuccess();
+
+    $this->assertStringContainsString('Pushed branch "testbranch" with commit message "Deployment commit"', $output);
+    $this->assertStringContainsString('Deployment finished successfully.', $output);
+
+    // Verify the branch exists in destination.
+    $this->gitCheckout($this->dst, 'testbranch');
+    $this->assertFilesExist($this->dst, 'f1');
+  }
+
+  /**
+   * Test deployment works with tag in detached HEAD state.
+   *
+   * When checked out at a tag, getOriginalBranch() should validate that
+   * the tag exists and allow deployment to proceed.
+   */
+  public function testDeploymentWithTagDetachedHead(): void {
+    $this->gitCreateFixtureCommits(1);
+
+    $repo = (new Git())->open($this->src);
+
+    // Create a tag at the current commit.
+    $repo->run('tag', 'v1.0.0');
+
+    // Checkout the tag to enter detached HEAD state.
+    $repo->checkout('v1.0.0');
+
+    // Deployment should work because tag is a valid detachment source.
+    $output = $this->assertArtifactCommandSuccess();
+
+    $this->assertStringContainsString('Pushed branch "testbranch" with commit message "Deployment commit"', $output);
+    $this->assertStringContainsString('Deployment finished successfully.', $output);
+  }
+
+}
diff --git a/tests/Unit/Exception/BranchNotFoundExceptionTest.php b/tests/Unit/Exception/BranchNotFoundExceptionTest.php
diff --git a/tests/Unit/Traits/FilesystemTraitTest.php b/tests/Unit/Traits/FilesystemTraitTest.php
diff --git a/tests/Unit/Traits/FilesystemTraitTestClass.php b/tests/Unit/Traits/FilesystemTraitTestClass.php

Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,7 @@ parameters:`
`13`	`13`	`excludePaths:`
`14`	`14`	`- vendor/*`
`15`	`15`	`- node_modules/*`
	`16`	`+ - tests/Unit/Traits/FilesystemTraitTestClass.php`
`16`	`17`
`17`	`18`	`ignoreErrors:`
`18`	`19`	`-`