[#23] Added '--cleanup-stale' option to prune stale remote branches. (#337)

Author: AlexSkrypnyk

README.md

@@ -168,6 +168,31 @@ repository would create a branch `deployment/1.2.3` in the destination
 repository. The addition of the new tags would create new unique branches in the
 destination repository.
 
+#### Cleanup of stale branches
+
+In `branch` mode the _destination_ repository accumulates a new branch for every
+deployment. Enable `--cleanup-stale` to remove old ones automatically after a
+successful push:
+
+```shell
+./git-artifact git@github.com:yourorg/your-repo-destination.git \
+  --mode=branch \
+  --branch="deployment/[tags:.]" \
+  --cleanup-stale \
+  --cleanup-pattern="deployment/*" \
+  --cleanup-age=3
+```
+
+Any branch in the _destination_ repository that matches `--cleanup-pattern` and
+whose last commit is older than `--cleanup-age` days is deleted. The branch that
+was just pushed and the _destination_ repository's default branch are never
+deleted. `--cleanup-pattern` is required - it is the only way to identify the
+branches created by your deployments - and is matched as a shell glob. Add
+`--dry-run` to preview deletions without performing them.
+
+Because deletion uses standard Git, this works with any remote (GitHub, GitLab,
+Bitbucket, self-hosted), not only GitHub.
+
 ## 📥 Installation
 
 ### As a standalone binary
@@ -269,6 +294,9 @@ fully-configured [example in the Vortex project](https://github.com/drevops/vort
 |----------------------------|---------------------|---------------------------------------------------------------------------------------------------------------------|
 | `--ansi`                   |                     | Force ANSI output. Use `--no-ansi` to disable                                                                       |
 | `--branch`                 | `[branch]`          | Destination branch with optional tokens (see below)                                                                 |
+| `--cleanup-age`            | `7`                 | Age in days after which a matching remote branch is considered stale; used with `--cleanup-stale`                    |
+| `--cleanup-pattern`        |                     | Glob pattern of remote branches eligible for stale cleanup (e.g. `deployment/*`); required with `--cleanup-stale`    |
+| `--cleanup-stale`          |                     | Delete stale remote branches that match `--cleanup-pattern` and are older than `--cleanup-age` days                  |
 | `--dry-run`                |                     | Run without pushing to the remote repository                                                                        |
 | `--fail-on-missing-branch` |                     | Fail artifact packaging if source branch cannot be determined. By default, artifact packaging is skipped gracefully |
 | `--gitignore`              |                     | Path to the `.gitignore` file to replace the current `.gitignore`                                                   |

src/Commands/ArtifactCommand.php

@@ -32,6 +32,8 @@ class ArtifactCommand extends Command {
 
   const MODE_FORCE_PUSH = 'force-push';
 
+  const CLEANUP_STALE_AGE_DEFAULT = 7;
+
   /**
    * Current Git repository.
    */
@@ -124,6 +126,21 @@ class ArtifactCommand extends Command {
    */
   protected bool $pushSuccessful = FALSE;
 
+  /**
+   * Flag to enable deletion of stale branches in the remote repository.
+   */
+  protected bool $cleanupStale = FALSE;
+
+  /**
+   * Glob pattern of remote branches eligible for stale cleanup.
+   */
+  protected string $cleanupPattern = '';
+
+  /**
+   * Age in days after which a matching remote branch is considered stale.
+   */
+  protected int $cleanupAge = self::CLEANUP_STALE_AGE_DEFAULT;
+
   /**
    * Internal option to set current timestamp.
    */
@@ -175,7 +192,10 @@ protected function configure(): void {
       ->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 during packaging 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 artifact packaging if source branch cannot be determined. By default, artifact packaging is skipped gracefully.');
+      ->addOption('fail-on-missing-branch', NULL, InputOption::VALUE_NONE,     'Fail artifact packaging if source branch cannot be determined. By default, artifact packaging is skipped gracefully.')
+      ->addOption('cleanup-stale',          NULL, InputOption::VALUE_NONE,     'Delete stale branches in the remote repository that match --cleanup-pattern and are older than --cleanup-age days.')
+      ->addOption('cleanup-pattern',        NULL, InputOption::VALUE_REQUIRED, 'Glob pattern of remote branches eligible for stale cleanup (e.g. "deployment/*"). Required when --cleanup-stale is set.')
+      ->addOption('cleanup-age',            NULL, InputOption::VALUE_REQUIRED, 'Age in days after which a matching remote branch is considered stale.', (string) self::CLEANUP_STALE_AGE_DEFAULT);
     // @formatter:on
     // phpcs:enable Generic.Functions.FunctionCallArgumentSpacing.TooMuchSpaceAfterComma
     // phpcs:enable Drupal.WhiteSpace.Comma.TooManySpaces
@@ -275,6 +295,8 @@ protected function doExecute(): void {
 
         $this->output->writeln(sprintf('<info>Pushed branch "%s" with commit message "%s"</info>', $this->destinationBranch, $this->commitMessage));
       }
+
+      $this->cleanupStaleBranches();
     }
     catch (GitException $exception) {
       $result = $exception->getRunnerResult();
@@ -318,6 +340,69 @@ protected function doExecute(): void {
     }
   }
 
+  /**
+   * Delete stale branches in the remote repository.
+   *
+   * Eligible branches are those matching the configured pattern whose tip
+   * commit is older than the configured age. The branch that was just pushed
+   * and the remote's default branch are always preserved. Cleanup is
+   * best-effort: any failure is logged and never fails the deployment, which
+   * has already succeeded by this point.
+   */
+  protected function cleanupStaleBranches(): void {
+    if (!$this->cleanupStale) {
+      return;
+    }
+
+    try {
+      $branches = $this->repo->getRemoteBranchesInfo($this->remoteName);
+    }
+    catch (GitException $exception) {
+      $this->output->writeln('<comment>Unable to list remote branches for cleanup.</comment>');
+      $this->logger->warning('Unable to list remote branches for cleanup: ' . $exception->getMessage());
+
+      return;
+    }
+
+    $default_branch = $this->repo->getRemoteDefaultBranch($this->remoteName);
+    if ($default_branch === NULL) {
+      $this->output->writeln('<comment>Unable to determine the remote default branch; skipping stale cleanup for safety.</comment>');
+      $this->logger->warning('Unable to determine the remote default branch; skipping stale cleanup for safety.');
+
+      return;
+    }
+
+    $protected_branches = [$this->destinationBranch, $default_branch];
+
+    $stale = ArtifactGitRepository::filterStaleBranches($branches, $this->cleanupPattern, $this->cleanupAge * 86400, $this->now, $protected_branches);
+
+    if ($stale === []) {
+      $this->output->writeln('<info>No stale branches to clean up.</info>');
+      $this->logger->notice('No stale branches to clean up.');
+
+      return;
+    }
+
+    foreach ($stale as $branch) {
+      if ($this->isDryRun) {
+        $this->output->writeln(sprintf('<info>Would delete stale branch "%s"</info>', $branch));
+        $this->logger->notice(sprintf('Would delete stale branch "%s"', $branch));
+
+        continue;
+      }
+
+      try {
+        $this->repo->deleteRemoteBranch($this->remoteName, $branch);
+        $this->output->writeln(sprintf('<info>Deleted stale branch "%s"</info>', $branch));
+        $this->logger->notice(sprintf('Deleted stale branch "%s"', $branch));
+      }
+      catch (GitException $exception) {
+        $this->output->writeln(sprintf('<comment>Failed to delete stale branch "%s"</comment>', $branch));
+        $this->logger->warning(sprintf('Failed to delete stale branch "%s": %s', $branch, $exception->getMessage()));
+      }
+    }
+  }
+
   /**
    * Resolve and validate CLI options values into internal values.
    *
@@ -340,6 +425,21 @@ protected function resolveOptions(string $url, array $options): void {
     $this->failOnMissingBranch = !empty($options['fail-on-missing-branch']);
     $this->logFile = empty($options['log']) || !is_string($options['log']) ? '' : $this->fsGetAbsolutePath($options['log']);
 
+    $this->cleanupStale = !empty($options['cleanup-stale']);
+    if ($this->cleanupStale) {
+      $pattern = isset($options['cleanup-pattern']) && is_string($options['cleanup-pattern']) ? trim($options['cleanup-pattern']) : '';
+      if ($pattern === '') {
+        throw new \RuntimeException('The --cleanup-pattern option is required when --cleanup-stale is set.');
+      }
+      $this->cleanupPattern = $pattern;
+
+      $age = $options['cleanup-age'] ?? NULL;
+      if (!is_numeric($age) || (float) $age != (int) $age || (int) $age < 1) {
+        throw new \RuntimeException('The --cleanup-age option must be a positive integer number of days.');
+      }
+      $this->cleanupAge = (int) $age;
+    }
+
     $this->setMode(is_string($options['mode']) ? $options['mode'] : '', $options);
 
     $this->sourceDir = empty($options['src']) || !is_string($options['src']) ? $this->fsGetRootDir() : $this->fsGetAbsolutePath($options['src']);
@@ -415,6 +515,9 @@ protected function showInfo(): void {
     $lines[] = (' Remote branch:         ' . $this->destinationBranch);
     $lines[] = (' Gitignore file:        ' . ($this->gitignoreFile ?: 'No'));
     $lines[] = (' Will push:             ' . ($this->isDryRun ? 'No' : 'Yes'));
+    if ($this->cleanupStale) {
+      $lines[] = (' Cleanup stale:         ' . sprintf('Yes (pattern "%s", older than %d days)', $this->cleanupPattern, $this->cleanupAge));
+    }
     $lines[] = ('----------------------------------------------------------------------');
 
     $this->output->writeln($lines);

src/Git/ArtifactGitRepository.php

@@ -217,6 +217,86 @@ protected function listRemotes(): array {
     return $this->extractFromCommand(['remote']) ?: [];
   }
 
+  /**
+   * Get remote branches with their tip commit timestamps.
+   *
+   * A shallow fetch populates the remote-tracking refs; only the tip commit
+   * metadata is required to determine branch age, so the fetch is limited to a
+   * depth of one.
+   *
+   * @param string $remote
+   *   Remote name.
+   *
+   * @return array<string, int>
+   *   Branch names keyed to the Unix timestamp of their tip commit.
+   */
+  public function getRemoteBranchesInfo(string $remote): array {
+    $this->run('fetch', '--depth=1', $remote);
+
+    $format = '%(refname:lstrip=3)|%(committerdate:unix)';
+    $lines = $this->extractFromCommand(['for-each-ref', '--format=' . $format, 'refs/remotes/' . $remote]) ?: [];
+
+    $branches = [];
+    foreach ($lines as $line) {
+      if (!str_contains($line, '|')) {
+        continue;
+      }
+
+      [$name, $timestamp] = explode('|', $line, 2);
+
+      if ($name === '' || $name === 'HEAD' || !is_numeric($timestamp)) {
+        continue;
+      }
+
+      $branches[$name] = (int) $timestamp;
+    }
+
+    return $branches;
+  }
+
+  /**
+   * Get the default branch of a remote.
+   *
+   * @param string $remote
+   *   Remote name.
+   *
+   * @return string|null
+   *   The default branch name, or NULL if it cannot be determined.
+   */
+  public function getRemoteDefaultBranch(string $remote): ?string {
+    try {
+      $lines = $this->extractFromCommand(['ls-remote', '--symref', $remote, 'HEAD']) ?: [];
+    }
+    catch (GitException) {
+      return NULL;
+    }
+
+    foreach ($lines as $line) {
+      if (preg_match('#^ref:\s+refs/heads/(\S+)\s+HEAD#', $line, $matches)) {
+        return $matches[1];
+      }
+    }
+
+    return NULL;
+  }
+
+  /**
+   * Delete a branch in the remote repository.
+   *
+   * @param string $remote
+   *   Remote name.
+   * @param string $branch
+   *   Branch name to delete.
+   *
+   * @return static
+   *   The git repository.
+   */
+  public function deleteRemoteBranch(string $remote, string $branch): static {
+    $this->run('push', $remote, '--delete', $branch);
+
+    return $this;
+  }
+
   /**
    * Get tag pointing to HEAD.
    *
@@ -433,6 +513,69 @@ public static function isValidRemote(string $uri, string $type = 'any'): bool {
     };
   }
 
+  /**
+   * Filter branches down to those eligible for stale cleanup.
+   *
+   * @param array<string, int> $branches
+   *   Branch names keyed to the Unix timestamp of their tip commit.
+   * @param string $pattern
+   *   Glob pattern; only branches matching it are eligible.
+   * @param int $max_age
+   *   Maximum allowed age in seconds; branches older than this are stale.
+   * @param int $now
+   *   Reference "current" Unix timestamp to measure age against.
+   * @param array<string> $protected_branches
+   *   Branch names that must never be returned.
+   *
+   * @return array<string>
+   *   Names of stale branches, sorted for deterministic output.
+   */
+  public static function filterStaleBranches(array $branches, string $pattern, int $max_age, int $now, array $protected_branches = []): array {
+    $stale = [];
+
+    foreach ($branches as $name => $timestamp) {
+      $name = (string) $name;
+
+      if (in_array($name, $protected_branches, TRUE)) {
+        continue;
+      }
+
+      if (!self::matchesGlob($pattern, $name)) {
+        continue;
+      }
+
+      if (($now - $timestamp) <= $max_age) {
+        continue;
+      }
+
+      $stale[] = $name;
+    }
+
+    sort($stale);
+
+    return $stale;
+  }
+
+  /**
+   * Test whether a branch name matches a shell-style glob pattern.
+   *
+   * Converts the glob into a regular expression so the match honours the
+   * same '*' and '?' semantics as a shell glob without using fnmatch().
+   *
+   * @param string $pattern
+   *   The glob pattern to match against (e.g. 'deployment/*').
+   * @param string $subject
+   *   The string to test.
+   *
+   * @return bool
+   *   TRUE when the subject matches the pattern.
+   */
+  protected static function matchesGlob(string $pattern, string $subject): bool {
+    $regex = '/^' . str_replace(['\*', '\?'], ['.*', '.'], preg_quote($pattern, '/')) . '$/';
+
+    return (bool) preg_match($regex, $subject);
+  }
+
   /**
    * Reset to the previous commit.
    */