github2gerrit 0.1.5__py3-none-any.whl → 0.1.7__py3-none-any.whl

github2gerrit/cli.py

@@ -8,6 +8,8 @@ import logging
 import os
 import tempfile
 from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures import as_completed
 from pathlib import Path
 from typing import TYPE_CHECKING
 from typing import Any
@@ -35,21 +37,13 @@ from .github_api import iter_open_pulls
 from .gitutils import run_cmd
 from .models import GitHubContext
 from .models import Inputs
-
-
-def _is_verbose_mode() -> bool:
-    """Check if verbose mode is enabled via environment variable."""
-    return os.getenv("G2G_VERBOSE", "").lower() in ("true", "1", "yes")
-
-
-def _log_exception_conditionally(
-    logger: logging.Logger, message: str, *args: Any
-) -> None:
-    """Log exception with traceback only if verbose mode is enabled."""
-    if _is_verbose_mode():
-        logger.exception(message, *args)
-    else:
-        logger.error(message, *args)
+from .ssh_common import build_git_ssh_command
+from .ssh_common import build_non_interactive_ssh_env
+from .utils import append_github_output
+from .utils import env_bool
+from .utils import env_str
+from .utils import log_exception_conditionally
+from .utils import parse_bool_env
 
 
 class ConfigurationError(Exception):
@@ -74,7 +68,7 @@ def _parse_github_target(url: str) -> tuple[str | None, str | None, int | None]:
     except Exception:
         return None, None, None
 
-    allow_ghe = _env_bool("ALLOW_GHE_URLS", False)
+    allow_ghe = env_bool("ALLOW_GHE_URLS", False)
     bad_hosts = {
         "gitlab.com",
         "www.gitlab.com",
@@ -120,13 +114,9 @@ class _ContextProto(Protocol):
 
 
 class _SingleUsageGroup(BaseGroup):
-    def format_usage(
-        self, ctx: _ContextProto, formatter: _FormatterProto
-    ) -> None:
+    def format_usage(self, ctx: _ContextProto, formatter: _FormatterProto) -> None:
         # Force a simplified usage line without COMMAND [ARGS]...
-        formatter.write_usage(
-            ctx.command_path, "[OPTIONS] TARGET_URL", prefix="Usage: "
-        )
+        formatter.write_usage(ctx.command_path, "[OPTIONS] TARGET_URL", prefix="Usage: ")
 
 
 # Error message constants to comply with TRY003
@@ -137,7 +127,7 @@ _MSG_ISSUE_ID_MULTILINE = "Issue ID must be single line"
 app: typer.Typer = typer.Typer(
     add_completion=False,
     no_args_is_help=False,
-    cls=_SingleUsageGroup,
+    cls=cast(Any, _SingleUsageGroup),
 )
 
 
@@ -154,9 +144,7 @@ def _resolve_org(default_org: str | None) -> str:
 if TYPE_CHECKING:
     F = TypeVar("F", bound=Callable[..., object])
 
-    def typed_app_command(
-        *args: object, **kwargs: object
-    ) -> Callable[[F], F]: ...
+    def typed_app_command(*args: object, **kwargs: object) -> Callable[[F], F]: ...
 else:
     typed_app_command = app.command
 
@@ -172,36 +160,38 @@ def main(
     submit_single_commits: bool = typer.Option(
         False,
         "--submit-single-commits",
+        envvar="SUBMIT_SINGLE_COMMITS",
         help="Submit one commit at a time to the Gerrit repository.",
     ),
     use_pr_as_commit: bool = typer.Option(
         False,
         "--use-pr-as-commit",
+        envvar="USE_PR_AS_COMMIT",
         help="Use PR title and body as the commit message.",
     ),
     fetch_depth: int = typer.Option(
         10,
         "--fetch-depth",
         envvar="FETCH_DEPTH",
-        help="Fetch-depth for the clone.",
+        help="Fetch depth for checkout.",
     ),
     gerrit_known_hosts: str = typer.Option(
         "",
         "--gerrit-known-hosts",
         envvar="GERRIT_KNOWN_HOSTS",
-        help="Known hosts entries for Gerrit SSH.",
+        help="Known hosts entries for Gerrit SSH (single or multi-line).",
     ),
     gerrit_ssh_privkey_g2g: str = typer.Option(
         "",
         "--gerrit-ssh-privkey-g2g",
         envvar="GERRIT_SSH_PRIVKEY_G2G",
-        help="SSH private key for Gerrit (string content).",
+        help="SSH private key content used to authenticate to Gerrit.",
     ),
     gerrit_ssh_user_g2g: str = typer.Option(
         "",
         "--gerrit-ssh-user-g2g",
         envvar="GERRIT_SSH_USER_G2G",
-        help="Gerrit SSH user.",
+        help="Gerrit SSH username (e.g. automation bot account).",
     ),
     gerrit_ssh_user_g2g_email: str = typer.Option(
         "",
@@ -269,12 +259,32 @@ def main(
         envvar="ALLOW_DUPLICATES",
         help="Allow submitting duplicate changes without error.",
     ),
+    ci_testing: bool = typer.Option(
+        False,
+        "--ci-testing/--no-ci-testing",
+        envvar="CI_TESTING",
+        help="Enable CI testing mode (overrides .gitreview, handles unrelated repos).",
+    ),
+    duplicates: str = typer.Option(
+        "open",
+        "--duplicates",
+        envvar="DUPLICATES",
+        help=(
+            'Gerrit statuses for duplicate detection (comma-separated). E.g. "open,merged,abandoned". Default: "open".'
+        ),
+    ),
+    normalise_commit: bool = typer.Option(
+        True,
+        "--normalise-commit/--no-normalise-commit",
+        envvar="NORMALISE_COMMIT",
+        help="Normalize commit messages to conventional commit format.",
+    ),
     verbose: bool = typer.Option(
         False,
         "--verbose",
         "-v",
         envvar="G2G_VERBOSE",
-        help="Enable verbose debug logging.",
+        help="Verbose output (sets loglevel to DEBUG).",
     ),
 ) -> None:
     """
@@ -289,16 +299,33 @@ def main(
     - No arguments for CI/CD environment; reads parameters from
       environment variables
     """
+    # Override boolean parameters with properly parsed environment variables
+    # This ensures that string "false" from GitHub Actions is handled correctly
+    if os.getenv("SUBMIT_SINGLE_COMMITS"):
+        submit_single_commits = parse_bool_env(os.getenv("SUBMIT_SINGLE_COMMITS"))
+
+    if os.getenv("USE_PR_AS_COMMIT"):
+        use_pr_as_commit = parse_bool_env(os.getenv("USE_PR_AS_COMMIT"))
+
+    if os.getenv("PRESERVE_GITHUB_PRS"):
+        preserve_github_prs = parse_bool_env(os.getenv("PRESERVE_GITHUB_PRS"))
+
+    if os.getenv("DRY_RUN"):
+        dry_run = parse_bool_env(os.getenv("DRY_RUN"))
+
+    if os.getenv("ALLOW_DUPLICATES"):
+        allow_duplicates = parse_bool_env(os.getenv("ALLOW_DUPLICATES"))
+
+    if os.getenv("CI_TESTING"):
+        ci_testing = parse_bool_env(os.getenv("CI_TESTING"))
     # Set up logging level based on verbose flag
     if verbose:
         os.environ["G2G_LOG_LEVEL"] = "DEBUG"
         _reconfigure_logging()
     # Normalize CLI options into environment for unified processing.
-    # For boolean flags, only set if explicitly provided via CLI
-    if submit_single_commits:
-        os.environ["SUBMIT_SINGLE_COMMITS"] = "true"
-    if use_pr_as_commit:
-        os.environ["USE_PR_AS_COMMIT"] = "true"
+    # Explicitly set all boolean flags to ensure consistent behavior
+    os.environ["SUBMIT_SINGLE_COMMITS"] = "true" if submit_single_commits else "false"
+    os.environ["USE_PR_AS_COMMIT"] = "true" if use_pr_as_commit else "false"
     os.environ["FETCH_DEPTH"] = str(fetch_depth)
     if gerrit_known_hosts:
         os.environ["GERRIT_KNOWN_HOSTS"] = gerrit_known_hosts
@@ -313,10 +340,9 @@ def main(
         os.environ["ORGANIZATION"] = resolved_org
     if reviewers_email:
         os.environ["REVIEWERS_EMAIL"] = reviewers_email
-    if preserve_github_prs:
-        os.environ["PRESERVE_GITHUB_PRS"] = "true"
-    if dry_run:
-        os.environ["DRY_RUN"] = "true"
+    os.environ["PRESERVE_GITHUB_PRS"] = "true" if preserve_github_prs else "false"
+    os.environ["DRY_RUN"] = "true" if dry_run else "false"
+    os.environ["NORMALISE_COMMIT"] = "true" if normalise_commit else "false"
     os.environ["ALLOW_GHE_URLS"] = "true" if allow_ghe_urls else "false"
     if gerrit_server:
         os.environ["GERRIT_SERVER"] = gerrit_server
@@ -326,8 +352,10 @@ def main(
         os.environ["GERRIT_PROJECT"] = gerrit_project
     if issue_id:
         os.environ["ISSUE_ID"] = issue_id
-    if allow_duplicates:
-        os.environ["ALLOW_DUPLICATES"] = "true"
+    os.environ["ALLOW_DUPLICATES"] = "true" if allow_duplicates else "false"
+    os.environ["CI_TESTING"] = "true" if ci_testing else "false"
+    if duplicates:
+        os.environ["DUPLICATES"] = duplicates
     # URL mode handling
     if target_url:
         org, repo, pr = _parse_github_target(target_url)
@@ -341,6 +369,12 @@ def main(
         else:
             os.environ["SYNC_ALL_OPEN_PRS"] = "true"
         os.environ["G2G_TARGET_URL"] = "1"
+    # Debug: Show environment at CLI startup
+    log.debug("CLI startup environment check:")
+    for key in ["DRY_RUN", "CI_TESTING", "GERRIT_SERVER", "GERRIT_PROJECT"]:
+        value = os.environ.get(key, "NOT_SET")
+        log.debug("  %s = %s", key, value)
+
     # Delegate to common processing path
     try:
         _process()
@@ -349,16 +383,13 @@ def main(
         raise
     except Exception as exc:
         log.debug("main(): _process failed: %s", exc)
-    return
+        raise typer.Exit(code=1) from exc
 
 
 def _setup_logging() -> logging.Logger:
     level_name = os.getenv("G2G_LOG_LEVEL", "INFO").upper()
     level = getattr(logging, level_name, logging.INFO)
-    fmt = (
-        "%(asctime)s %(levelname)-8s %(name)s "
-        "%(filename)s:%(lineno)d | %(message)s"
-    )
+    fmt = "%(asctime)s %(levelname)-8s %(name)s %(filename)s:%(lineno)d | %(message)s"
     logging.basicConfig(level=level, format=fmt)
     return logging.getLogger(APP_NAME)
 
@@ -375,51 +406,93 @@ def _reconfigure_logging() -> None:
 log = _setup_logging()
 
 
-def _env_str(name: str, default: str = "") -> str:
-    val = os.getenv(name)
-    return val if val is not None else default
-
-
-def _env_bool(name: str, default: bool = False) -> bool:
-    val = os.getenv(name)
-    if val is None:
-        return default
-    s = val.strip().lower()
-    return s in ("1", "true", "yes", "on")
-
-
 def _build_inputs_from_env() -> Inputs:
     return Inputs(
-        submit_single_commits=_env_bool("SUBMIT_SINGLE_COMMITS", False),
-        use_pr_as_commit=_env_bool("USE_PR_AS_COMMIT", False),
-        fetch_depth=int(_env_str("FETCH_DEPTH", "10") or "10"),
-        gerrit_known_hosts=_env_str("GERRIT_KNOWN_HOSTS"),
-        gerrit_ssh_privkey_g2g=_env_str("GERRIT_SSH_PRIVKEY_G2G"),
-        gerrit_ssh_user_g2g=_env_str("GERRIT_SSH_USER_G2G"),
-        gerrit_ssh_user_g2g_email=_env_str("GERRIT_SSH_USER_G2G_EMAIL"),
-        organization=_env_str(
-            "ORGANIZATION", _env_str("GITHUB_REPOSITORY_OWNER")
-        ),
-        reviewers_email=_env_str("REVIEWERS_EMAIL", ""),
-        preserve_github_prs=_env_bool("PRESERVE_GITHUB_PRS", False),
-        dry_run=_env_bool("DRY_RUN", False),
-        gerrit_server=_env_str("GERRIT_SERVER", ""),
-        gerrit_server_port=_env_str("GERRIT_SERVER_PORT", "29418"),
-        gerrit_project=_env_str("GERRIT_PROJECT"),
-        issue_id=_env_str("ISSUE_ID"),
-        allow_duplicates=_env_bool("ALLOW_DUPLICATES", False),
+        submit_single_commits=env_bool("SUBMIT_SINGLE_COMMITS", False),
+        use_pr_as_commit=env_bool("USE_PR_AS_COMMIT", False),
+        fetch_depth=int(env_str("FETCH_DEPTH", "10") or "10"),
+        gerrit_known_hosts=env_str("GERRIT_KNOWN_HOSTS"),
+        gerrit_ssh_privkey_g2g=env_str("GERRIT_SSH_PRIVKEY_G2G"),
+        gerrit_ssh_user_g2g=env_str("GERRIT_SSH_USER_G2G"),
+        gerrit_ssh_user_g2g_email=env_str("GERRIT_SSH_USER_G2G_EMAIL"),
+        organization=env_str("ORGANIZATION", env_str("GITHUB_REPOSITORY_OWNER")),
+        reviewers_email=env_str("REVIEWERS_EMAIL", ""),
+        preserve_github_prs=env_bool("PRESERVE_GITHUB_PRS", False),
+        dry_run=env_bool("DRY_RUN", False),
+        normalise_commit=env_bool("NORMALISE_COMMIT", True),
+        gerrit_server=env_str("GERRIT_SERVER", ""),
+        gerrit_server_port=env_str("GERRIT_SERVER_PORT", "29418"),
+        gerrit_project=env_str("GERRIT_PROJECT"),
+        issue_id=env_str("ISSUE_ID", ""),
+        allow_duplicates=env_bool("ALLOW_DUPLICATES", False),
+        ci_testing=env_bool("CI_TESTING", False),
+        duplicates_filter=env_str("DUPLICATES", "open"),
     )
 
 
-def _process_bulk(data: Inputs, gh: GitHubContext) -> None:
+def _process_bulk(data: Inputs, gh: GitHubContext) -> bool:
     client = build_client()
     repo = get_repo_from_env(client)
 
     all_urls: list[str] = []
     all_nums: list[str] = []
+    all_shas: list[str] = []
 
     prs_list = list(iter_open_pulls(repo))
     log.info("Found %d open PRs to process", len(prs_list))
+
+    # Result tracking for summary
+    processed_count = 0
+    succeeded_count = 0
+    skipped_count = 0
+    failed_count = 0
+
+    # Use bounded parallel processing with shared clients
+    max_workers = min(4, max(1, len(prs_list)))  # Cap at 4 workers
+
+    def process_single_pr(
+        pr_data: tuple[Any, models.GitHubContext],
+    ) -> tuple[str, SubmissionResult | None, Exception | None]:
+        """Process a single PR and return (status, result, exception)."""
+        pr, per_ctx = pr_data
+        pr_number = int(getattr(pr, "number", 0) or 0)
+
+        if pr_number <= 0:
+            return "invalid", None, None
+
+        log.info("Starting processing of PR #%d", pr_number)
+        log.debug(
+            "Processing PR #%d in multi-PR mode with event_name=%s, event_action=%s",
+            pr_number,
+            gh.event_name,
+            gh.event_action,
+        )
+
+        try:
+            if data.duplicates_filter:
+                os.environ["DUPLICATES"] = data.duplicates_filter
+            check_for_duplicates(per_ctx, allow_duplicates=data.allow_duplicates)
+        except DuplicateChangeError as exc:
+            log_exception_conditionally(log, "Skipping PR #%d", pr_number)
+            log.warning(
+                "Skipping PR #%d due to duplicate detection: %s. Use --allow-duplicates to override this check.",
+                pr_number,
+                exc,
+            )
+            return "skipped", None, exc
+
+        try:
+            with tempfile.TemporaryDirectory() as temp_dir:
+                workspace = Path(temp_dir)
+                orch = Orchestrator(workspace=workspace)
+                result_multi = orch.execute(inputs=data, gh=per_ctx)
+                return "success", result_multi, None
+        except Exception as exc:
+            log_exception_conditionally(log, "Failed to process PR #%d", pr_number)
+            return "failed", None, exc
+
+    # Prepare PR processing tasks
+    pr_tasks = []
     for pr in prs_list:
         pr_number = int(getattr(pr, "number", 0) or 0)
         if pr_number <= 0:
@@ -438,75 +511,85 @@ def _process_bulk(data: Inputs, gh: GitHubContext) -> None:
             head_ref=gh.head_ref,
             pr_number=pr_number,
         )
+        pr_tasks.append((pr, per_ctx))
 
-        log.info("Starting processing of PR #%d", pr_number)
-        log.debug(
-            "Processing PR #%d in multi-PR mode with event_name=%s, "
-            "event_action=%s",
-            pr_number,
-            gh.event_name,
-            gh.event_action,
-        )
+    # Process PRs in parallel
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        log.info("Processing %d PRs with %d parallel workers", len(pr_tasks), max_workers)
 
-        try:
-            check_for_duplicates(
-                per_ctx, allow_duplicates=data.allow_duplicates
-            )
-        except DuplicateChangeError as exc:
-            _log_exception_conditionally(log, "Skipping PR #%d", pr_number)
-            typer.echo(f"Skipping PR #{pr_number}: {exc}")
-            continue
+        # Submit all tasks
+        future_to_pr = {
+            executor.submit(process_single_pr, pr_task): pr_task[1].pr_number
+            for pr_task in pr_tasks
+            if pr_task[1].pr_number is not None
+        }
 
-        try:
-            with tempfile.TemporaryDirectory() as temp_dir:
-                workspace = Path(temp_dir)
-                orch = Orchestrator(workspace=workspace)
-                result_multi = orch.execute(inputs=data, gh=per_ctx)
-                if result_multi.change_urls:
-                    all_urls.extend(result_multi.change_urls)
-                    for url in result_multi.change_urls:
-                        log.info("Gerrit change URL: %s", url)
-                        log.info(
-                            "PR #%d created Gerrit change: %s",
-                            pr_number,
-                            url,
-                        )
-                if result_multi.change_numbers:
-                    all_nums.extend(result_multi.change_numbers)
-                    log.info(
-                        "PR #%d change numbers: %s",
-                        pr_number,
-                        result_multi.change_numbers,
-                    )
-        except Exception as exc:
-            _log_exception_conditionally(
-                log, "Failed to process PR #%d", pr_number
-            )
-            typer.echo(f"Failed to process PR #{pr_number}: {exc}")
-            log.info("Continuing to next PR despite failure")
-            continue
+        # Collect results as they complete
+        for future in as_completed(future_to_pr):
+            pr_number = future_to_pr[future]
+            processed_count += 1
+
+            try:
+                status, result_multi, exc = future.result()
+
+                if status == "success" and result_multi:
+                    succeeded_count += 1
+                    if result_multi.change_urls:
+                        all_urls.extend(result_multi.change_urls)
+                        for url in result_multi.change_urls:
+                            log.info("Gerrit change URL: %s", url)
+                            log.info("PR #%d created Gerrit change: %s", pr_number, url)
+                    if result_multi.change_numbers:
+                        all_nums.extend(result_multi.change_numbers)
+                        log.info("PR #%d change numbers: %s", pr_number, result_multi.change_numbers)
+                    if result_multi.commit_shas:
+                        all_shas.extend(result_multi.commit_shas)
+                elif status == "skipped":
+                    skipped_count += 1
+                elif status == "failed":
+                    failed_count += 1
+                    typer.echo(f"Failed to process PR #{pr_number}: {exc}")
+                    log.info("Continuing to next PR despite failure")
+                else:
+                    failed_count += 1
 
+            except Exception as exc:
+                failed_count += 1
+                log_exception_conditionally(log, "Failed to process PR #%d", pr_number)
+                typer.echo(f"Failed to process PR #{pr_number}: {exc}")
+                log.info("Continuing to next PR despite failure")
+
+    # Aggregate results and provide summary
     if all_urls:
         os.environ["GERRIT_CHANGE_REQUEST_URL"] = "\n".join(all_urls)
     if all_nums:
         os.environ["GERRIT_CHANGE_REQUEST_NUM"] = "\n".join(all_nums)
+    if all_shas:
+        os.environ["GERRIT_COMMIT_SHA"] = "\n".join(all_shas)
 
-    _append_github_output(
+    append_github_output(
         {
-            "gerrit_change_request_url": os.getenv(
-                "GERRIT_CHANGE_REQUEST_URL", ""
-            ),
-            "gerrit_change_request_num": os.getenv(
-                "GERRIT_CHANGE_REQUEST_NUM", ""
-            ),
+            "gerrit_change_request_url": "\n".join(all_urls) if all_urls else "",
+            "gerrit_change_request_num": "\n".join(all_nums) if all_nums else "",
+            "gerrit_commit_sha": "\n".join(all_shas) if all_shas else "",
         }
     )
 
-    log.info("Submission pipeline complete (multi-PR).")
-    return
+    # Summary block
+    log.info("=" * 60)
+    log.info("BULK PROCESSING SUMMARY:")
+    log.info("  Total PRs processed: %d", processed_count)
+    log.info("  Succeeded: %d", succeeded_count)
+    log.info("  Skipped (duplicates): %d", skipped_count)
+    log.info("  Failed: %d", failed_count)
+    log.info("  Gerrit changes created: %d", len(all_urls))
+    log.info("=" * 60)
+
+    # Return True if no failures occurred
+    return failed_count == 0
 
 
-def _process_single(data: Inputs, gh: GitHubContext) -> None:
+def _process_single(data: Inputs, gh: GitHubContext) -> bool:
     # Create temporary directory for all git operations
     with tempfile.TemporaryDirectory() as temp_dir:
         workspace = Path(temp_dir)
@@ -524,48 +607,32 @@ def _process_single(data: Inputs, gh: GitHubContext) -> None:
         except Exception as exc:
             log.debug("Execution failed; continuing to write outputs: %s", exc)
 
-            result = SubmissionResult(
-                change_urls=[], change_numbers=[], commit_shas=[]
-            )
+            result = SubmissionResult(change_urls=[], change_numbers=[], commit_shas=[])
         if result.change_urls:
-            os.environ["GERRIT_CHANGE_REQUEST_URL"] = "\n".join(
-                result.change_urls
-            )
+            os.environ["GERRIT_CHANGE_REQUEST_URL"] = "\n".join(result.change_urls)
             # Output Gerrit change URL(s) to console
             for url in result.change_urls:
                 log.info("Gerrit change URL: %s", url)
         if result.change_numbers:
-            os.environ["GERRIT_CHANGE_REQUEST_NUM"] = "\n".join(
-                result.change_numbers
-            )
+            os.environ["GERRIT_CHANGE_REQUEST_NUM"] = "\n".join(result.change_numbers)
+        if result.commit_shas:
+            os.environ["GERRIT_COMMIT_SHA"] = "\n".join(result.commit_shas)
 
         # Also write outputs to GITHUB_OUTPUT if available
-        _append_github_output(
+        append_github_output(
             {
-                "gerrit_change_request_url": os.getenv(
-                    "GERRIT_CHANGE_REQUEST_URL", ""
-                ),
-                "gerrit_change_request_num": os.getenv(
-                    "GERRIT_CHANGE_REQUEST_NUM", ""
-                ),
-                "gerrit_commit_sha": os.getenv("GERRIT_COMMIT_SHA", ""),
+                "gerrit_change_request_url": "\n".join(result.change_urls) if result.change_urls else "",
+                "gerrit_change_request_num": "\n".join(result.change_numbers) if result.change_numbers else "",
+                "gerrit_commit_sha": "\n".join(result.commit_shas) if result.commit_shas else "",
             }
         )
 
-        if pipeline_success:
-            log.info("Submission pipeline completed SUCCESSFULLY ✅")
-        else:
-            log.error("Submission pipeline FAILED ❌")
-        return
+        return pipeline_success
 
 
-def _prepare_local_checkout(
-    workspace: Path, gh: GitHubContext, data: Inputs
-) -> None:
+def _prepare_local_checkout(workspace: Path, gh: GitHubContext, data: Inputs) -> None:
     repo_full = gh.repository.strip() if gh.repository else ""
-    server_url = gh.server_url or os.getenv(
-        "GITHUB_SERVER_URL", "https://github.com"
-    )
+    server_url = gh.server_url or os.getenv("GITHUB_SERVER_URL", "https://github.com")
     server_url = (server_url or "https://github.com").rstrip("/")
     base_ref = gh.base_ref or ""
     pr_num_str: str = str(gh.pr_number) if gh.pr_number else "0"
@@ -573,11 +640,52 @@ def _prepare_local_checkout(
     if not repo_full:
         return
 
-    repo_url = f"{server_url}/{repo_full}.git"
+    # Try SSH first for private repos if available, then fall back to HTTPS/API
+    repo_ssh_url = f"git@{server_url.replace('https://', '').replace('http://', '')}:{repo_full}.git"
+    repo_https_url = f"{server_url}/{repo_full}.git"
+
     run_cmd(["git", "init"], cwd=workspace)
+
+    # Determine which URL to use and set up authentication
+    env: dict[str, str] = {}
+    repo_url = repo_https_url  # Default to HTTPS
+
+    # Check if we should try SSH for private repos
+    use_ssh = False
+    respect_user_ssh = os.getenv("G2G_RESPECT_USER_SSH", "false").lower() in ("true", "1", "yes")
+    gerrit_ssh_privkey = os.getenv("GERRIT_SSH_PRIVKEY_G2G")
+
+    log.debug(
+        "GitHub repo access decision: SSH URL available=%s, G2G_RESPECT_USER_SSH=%s, GERRIT_SSH_PRIVKEY_G2G=%s",
+        repo_ssh_url.startswith("git@"),
+        respect_user_ssh,
+        bool(gerrit_ssh_privkey),
+    )
+
+    if repo_ssh_url.startswith("git@"):
+        # For private repos, only try SSH if G2G_RESPECT_USER_SSH is explicitly enabled
+        # Don't use SSH just because GERRIT_SSH_PRIVKEY_G2G is set (that's for Gerrit, not GitHub)
+        if respect_user_ssh:
+            use_ssh = True
+            repo_url = repo_ssh_url
+            log.debug("Using SSH for GitHub repo access due to G2G_RESPECT_USER_SSH=true")
+        else:
+            log.debug("Not using SSH for GitHub repo access - G2G_RESPECT_USER_SSH not enabled")
+
+    if use_ssh:
+        env = {
+            "GIT_SSH_COMMAND": build_git_ssh_command(),
+            **build_non_interactive_ssh_env(),
+        }
+        log.debug("Using SSH URL for private repo: %s", repo_url)
+    else:
+        log.debug("Using HTTPS URL: %s", repo_url)
+
     run_cmd(["git", "remote", "add", "origin", repo_url], cwd=workspace)
 
-    # Fetch base branch and PR head
+    # Fetch base branch and PR head with fallback to API archive
+    fetch_success = False
+
     if base_ref:
         try:
             branch_ref = f"refs/heads/{base_ref}:refs/remotes/origin/{base_ref}"
@@ -590,35 +698,174 @@ def _prepare_local_checkout(
                     branch_ref,
                 ],
                 cwd=workspace,
+                env=env,
             )
         except Exception as exc:
             log.debug("Base branch fetch failed for %s: %s", base_ref, exc)
 
     if pr_num_str:
-        pr_ref = (
-            f"refs/pull/{pr_num_str}/head:"
-            f"refs/remotes/origin/pr/{pr_num_str}/head"
-        )
-        run_cmd(
-            [
-                "git",
-                "fetch",
-                f"--depth={data.fetch_depth}",
-                "origin",
-                pr_ref,
-            ],
-            cwd=workspace,
-        )
-        run_cmd(
-            [
-                "git",
-                "checkout",
-                "-B",
-                "g2g_pr_head",
-                f"refs/remotes/origin/pr/{pr_num_str}/head",
-            ],
-            cwd=workspace,
-        )
+        try:
+            pr_ref = f"refs/pull/{pr_num_str}/head:refs/remotes/origin/pr/{pr_num_str}/head"
+            run_cmd(
+                [
+                    "git",
+                    "fetch",
+                    f"--depth={data.fetch_depth}",
+                    "origin",
+                    pr_ref,
+                ],
+                cwd=workspace,
+                env=env,
+            )
+            run_cmd(
+                [
+                    "git",
+                    "checkout",
+                    "-B",
+                    "g2g_pr_head",
+                    f"refs/remotes/origin/pr/{pr_num_str}/head",
+                ],
+                cwd=workspace,
+                env=env,
+            )
+            fetch_success = True
+        except Exception as exc:
+            log.warning("Git fetch failed, attempting API archive fallback: %s", exc)
+            # Try API archive fallback for private repos
+            try:
+                _fallback_to_api_archive(workspace, gh, data, pr_num_str)
+                fetch_success = True
+            except Exception as api_exc:
+                log.exception("API archive fallback also failed")
+                raise exc from api_exc
+
+    if not fetch_success and pr_num_str:
+        msg = f"Failed to prepare checkout for PR #{pr_num_str}"
+        raise RuntimeError(msg)
+
+
+def _fallback_to_api_archive(workspace: Path, gh: GitHubContext, data: Inputs, pr_num_str: str) -> None:
+    """Fallback to GitHub API archive download for private repos."""
+    import io
+    import json
+    import shutil
+    import zipfile
+    from urllib.request import Request
+    from urllib.request import urlopen
+
+    log.info("Attempting API archive fallback for PR #%s", pr_num_str)
+
+    # Get GitHub token for authenticated requests
+    token = os.getenv("GITHUB_TOKEN")
+    if not token:
+        msg = "GITHUB_TOKEN required for API archive fallback"
+        raise RuntimeError(msg)
+
+    # Build API URLs
+    repo_full = gh.repository
+    server_url = gh.server_url or "https://github.com"
+
+    # Construct GitHub API base URL properly
+    if "github.com" in server_url:
+        # For github.com, use api.github.com
+        api_base = "https://api.github.com"
+    elif server_url.startswith("https://"):
+        # For GitHub Enterprise, append /api/v3
+        api_base = server_url.rstrip("/") + "/api/v3"
+    else:
+        # Fallback for unexpected formats
+        api_base = "https://api.github.com"
+
+    # Get PR details to find head SHA
+    pr_api_url = f"{api_base}/repos/{repo_full}/pulls/{pr_num_str}"
+    log.debug("GitHub API PR URL: %s", pr_api_url)
+
+    headers = {
+        "Authorization": f"token {token}",
+        "Accept": "application/vnd.github.v3+json",
+        "User-Agent": "github2gerrit",
+    }
+
+    try:
+        req = Request(pr_api_url, headers=headers)  # noqa: S310
+        with urlopen(req, timeout=30) as response:  # noqa: S310
+            pr_data = json.loads(response.read().decode())
+    except Exception:
+        log.exception("Failed to fetch PR data from GitHub API")
+        log.debug("PR API URL was: %s", pr_api_url)
+        raise
+
+    head_sha = pr_data["head"]["sha"]
+
+    # Download archive
+    archive_url = f"{api_base}/repos/{repo_full}/zipball/{head_sha}"
+    log.debug("GitHub API archive URL: %s", archive_url)
+
+    try:
+        req = Request(archive_url, headers=headers)  # noqa: S310
+        with urlopen(req, timeout=120) as response:  # noqa: S310
+            archive_data = response.read()
+    except Exception:
+        log.exception("Failed to download archive from GitHub API")
+        log.debug("Archive URL was: %s", archive_url)
+        raise
+
+    # Extract archive
+    with zipfile.ZipFile(io.BytesIO(archive_data)) as zf:
+        # Find the root directory in the archive (usually repo-sha format)
+        members = zf.namelist()
+        root_dir = None
+        for member in members:
+            if "/" in member:
+                root_dir = member.split("/")[0]
+                break
+
+        if not root_dir:
+            msg = "Could not find root directory in archive"
+            raise RuntimeError(msg)
+
+        # Extract to temporary location then move contents
+        extract_path = workspace / "archive_temp"
+        zf.extractall(extract_path)
+
+        # Move contents from extracted root to workspace
+        extracted_root = extract_path / root_dir
+        for item in extracted_root.iterdir():
+            if item.name == ".git":
+                continue  # Skip .git if present
+            dest = workspace / item.name
+            if dest.exists():
+                if dest.is_dir():
+                    shutil.rmtree(dest)
+                else:
+                    dest.unlink()
+            item.rename(dest)
+
+        # Clean up
+        shutil.rmtree(extract_path)
+
+    # Set up git for the extracted content
+    if not (workspace / ".git").exists():
+        run_cmd(["git", "init"], cwd=workspace)
+
+    # Create a commit for the PR content
+    run_cmd(["git", "add", "."], cwd=workspace)
+    run_cmd(
+        [
+            "git",
+            "commit",
+            "-m",
+            f"PR #{pr_num_str} content from API archive",
+            "--author",
+            "GitHub API <noreply@github.com>",
+        ],
+        cwd=workspace,
+    )
+
+    # Create the expected branch
+    run_cmd(["git", "checkout", "-B", "g2g_pr_head"], cwd=workspace)
+
+    log.info("Successfully extracted PR #%s content via API archive", pr_num_str)
 
 
 def _load_effective_inputs() -> Inputs:
@@ -626,25 +873,28 @@ def _load_effective_inputs() -> Inputs:
     data = _build_inputs_from_env()
 
     # Load per-org configuration and apply to environment before validation
-    org_for_cfg = (
-        data.organization
-        or os.getenv("ORGANIZATION")
-        or os.getenv("GITHUB_REPOSITORY_OWNER")
-    )
+    org_for_cfg = data.organization or os.getenv("ORGANIZATION") or os.getenv("GITHUB_REPOSITORY_OWNER")
     cfg = load_org_config(org_for_cfg)
 
     # Apply dynamic parameter derivation for missing Gerrit parameters
     cfg = apply_parameter_derivation(cfg, org_for_cfg, save_to_config=True)
 
+    # Debug: Show what configuration would be applied
+    log.debug("Configuration to apply: %s", cfg)
+    if "DRY_RUN" in cfg:
+        log.warning(
+            "Configuration contains DRY_RUN=%s, this may override environment DRY_RUN=%s",
+            cfg["DRY_RUN"],
+            os.getenv("DRY_RUN"),
+        )
+
     apply_config_to_env(cfg)
 
     # Refresh inputs after applying configuration to environment
     data = _build_inputs_from_env()
 
     # Derive reviewers from local git config if running locally and unset
-    if not os.getenv("REVIEWERS_EMAIL") and (
-        os.getenv("G2G_TARGET_URL") or not os.getenv("GITHUB_EVENT_NAME")
-    ):
+    if not os.getenv("REVIEWERS_EMAIL") and (os.getenv("G2G_TARGET_URL") or not os.getenv("GITHUB_EVENT_NAME")):
         try:
             from .gitutils import enumerate_reviewer_emails
 
@@ -663,11 +913,14 @@ def _load_effective_inputs() -> Inputs:
                     reviewers_email=os.environ["REVIEWERS_EMAIL"],
                     preserve_github_prs=data.preserve_github_prs,
                     dry_run=data.dry_run,
+                    normalise_commit=data.normalise_commit,
                     gerrit_server=data.gerrit_server,
                     gerrit_server_port=data.gerrit_server_port,
                     gerrit_project=data.gerrit_project,
                     issue_id=data.issue_id,
                     allow_duplicates=data.allow_duplicates,
+                    ci_testing=data.ci_testing,
+                    duplicates_filter=data.duplicates_filter,
                 )
                 log.info("Derived reviewers: %s", data.reviewers_email)
         except Exception as exc:
@@ -676,44 +929,15 @@ def _load_effective_inputs() -> Inputs:
     return data
 
 
-def _append_github_output(outputs: dict[str, str]) -> None:
-    gh_out = os.getenv("GITHUB_OUTPUT")
-    if not gh_out:
-        return
-    try:
-        with open(gh_out, "a", encoding="utf-8") as fh:
-            for key, val in outputs.items():
-                if not val:
-                    continue
-                if "\n" in val:
-                    fh.write(f"{key}<<G2G\n")
-                    fh.write(f"{val}\n")
-                    fh.write("G2G\n")
-                else:
-                    fh.write(f"{key}={val}\n")
-    except Exception as exc:
-        log.debug("Failed to write GITHUB_OUTPUT: %s", exc)
-
-
 def _augment_pr_refs_if_needed(gh: GitHubContext) -> GitHubContext:
-    if (
-        os.getenv("G2G_TARGET_URL")
-        and gh.pr_number
-        and (not gh.head_ref or not gh.base_ref)
-    ):
+    if os.getenv("G2G_TARGET_URL") and gh.pr_number and (not gh.head_ref or not gh.base_ref):
         try:
             client = build_client()
             repo = get_repo_from_env(client)
             pr_obj = get_pull(repo, int(gh.pr_number))
-            base_ref = str(
-                getattr(getattr(pr_obj, "base", object()), "ref", "") or ""
-            )
-            head_ref = str(
-                getattr(getattr(pr_obj, "head", object()), "ref", "") or ""
-            )
-            head_sha = str(
-                getattr(getattr(pr_obj, "head", object()), "sha", "") or ""
-            )
+            base_ref = str(getattr(getattr(pr_obj, "base", object()), "ref", "") or "")
+            head_ref = str(getattr(getattr(pr_obj, "head", object()), "ref", "") or "")
+            head_sha = str(getattr(getattr(pr_obj, "head", object()), "sha", "") or "")
             if base_ref:
                 os.environ["GITHUB_BASE_REF"] = base_ref
                 log.info("Resolved base_ref via GitHub API: %s", base_ref)
@@ -736,7 +960,7 @@ def _process() -> None:
     try:
         _validate_inputs(data)
     except ConfigurationError as exc:
-        _log_exception_conditionally(log, "Configuration validation failed")
+        log_exception_conditionally(log, "Configuration validation failed")
         typer.echo(f"Configuration validation failed: {exc}", err=True)
         raise typer.Exit(code=2) from exc
 
@@ -744,28 +968,40 @@ def _process() -> None:
     _log_effective_config(data, gh)
 
     # Test mode: short-circuit after validation
-    if _env_bool("G2G_TEST_MODE", False):
+    if env_bool("G2G_TEST_MODE", False):
         log.info("Validation complete. Ready to execute submission pipeline.")
         typer.echo("Validation complete. Ready to execute submission pipeline.")
         return
 
     # Bulk mode for URL/workflow_dispatch
-    sync_all = _env_bool("SYNC_ALL_OPEN_PRS", False)
-    if sync_all and (
-        gh.event_name == "workflow_dispatch" or os.getenv("G2G_TARGET_URL")
-    ):
-        _process_bulk(data, gh)
+    sync_all = env_bool("SYNC_ALL_OPEN_PRS", False)
+    if sync_all and (gh.event_name == "workflow_dispatch" or os.getenv("G2G_TARGET_URL")):
+        bulk_success = _process_bulk(data, gh)
+
+        # Log external API metrics summary
+        try:
+            from .external_api import log_api_metrics_summary
+
+            log_api_metrics_summary()
+        except Exception as exc:
+            log.debug("Failed to log API metrics summary: %s", exc)
+
+        # Final success/failure message for bulk processing
+        if bulk_success:
+            log.info("Bulk processing completed SUCCESSFULLY ✅")
+        else:
+            log.error("Bulk processing FAILED ❌")
+            raise typer.Exit(code=1)
+
         return
 
     if not gh.pr_number:
         log.error(
-            "PR_NUMBER is empty. This tool requires a valid pull request "
-            "context. Current event: %s",
+            "PR_NUMBER is empty. This tool requires a valid pull request context. Current event: %s",
             gh.event_name,
         )
         typer.echo(
-            "PR_NUMBER is empty. This tool requires a valid pull request "
-            f"context. Current event: {gh.event_name}",
+            f"PR_NUMBER is empty. This tool requires a valid pull request context. Current event: {gh.event_name}",
             err=True,
         )
         raise typer.Exit(code=2)
@@ -777,18 +1013,37 @@ def _process() -> None:
     gh = _augment_pr_refs_if_needed(gh)
 
     # Check for duplicates in single-PR mode (before workspace setup)
-    if gh.pr_number and not _env_bool("SYNC_ALL_OPEN_PRS", False):
+    if gh.pr_number and not env_bool("SYNC_ALL_OPEN_PRS", False):
         try:
+            if data.duplicates_filter:
+                os.environ["DUPLICATES"] = data.duplicates_filter
             check_for_duplicates(gh, allow_duplicates=data.allow_duplicates)
         except DuplicateChangeError as exc:
-            _log_exception_conditionally(log, "Duplicate change detected")
-            typer.echo(f"Error: {exc}", err=True)
-            typer.echo(
-                "Use --allow-duplicates to override this check.", err=True
+            log_exception_conditionally(
+                log,
+                "Duplicate detection blocked submission for PR #%d",
+                gh.pr_number,
             )
+            log.info("Use --allow-duplicates to override this check.")
             raise typer.Exit(code=3) from exc
 
-    _process_single(data, gh)
+    pipeline_success = _process_single(data, gh)
+
+    # Log external API metrics summary
+    try:
+        from .external_api import log_api_metrics_summary
+
+        log_api_metrics_summary()
+    except Exception as exc:
+        log.debug("Failed to log API metrics summary: %s", exc)
+
+    # Final success/failure message after all cleanup
+    if pipeline_success:
+        log.info("Submission pipeline completed SUCCESSFULLY ✅")
+    else:
+        log.error("Submission pipeline FAILED ❌")
+        raise typer.Exit(code=1)
+
     return
 
 
@@ -804,9 +1059,7 @@ def _load_event(path: Path | None) -> dict[str, Any]:
     if not path or not path.exists():
         return {}
     try:
-        return cast(
-            dict[str, Any], json.loads(path.read_text(encoding="utf-8"))
-        )
+        return cast(dict[str, Any], json.loads(path.read_text(encoding="utf-8")))
     except Exception as exc:
         log.warning("Failed to parse GITHUB_EVENT_PATH: %s", exc)
         return {}
@@ -873,10 +1126,7 @@ def _read_github_context() -> GitHubContext:
 
 def _validate_inputs(data: Inputs) -> None:
     if data.use_pr_as_commit and data.submit_single_commits:
-        msg = (
-            "USE_PR_AS_COMMIT and SUBMIT_SINGLE_COMMITS cannot be enabled at "
-            "the same time"
-        )
+        msg = "USE_PR_AS_COMMIT and SUBMIT_SINGLE_COMMITS cannot be enabled at the same time"
         raise ConfigurationError(msg)
 
     # Context-aware validation: different requirements for GH Actions vs CLI
@@ -890,7 +1140,6 @@ def _validate_inputs(data: Inputs) -> None:
     if is_github_actions:
         # In GitHub Actions: allow derivation if organization is available
         if not data.organization:
-            # No organization means no derivation possible
             required_fields.extend(
                 [
                     "gerrit_ssh_user_g2g",
@@ -901,9 +1150,7 @@ def _validate_inputs(data: Inputs) -> None:
         # In local CLI: require explicit values or organization + derivation
         # This prevents unexpected behavior when running locally
         missing_gerrit_params = [
-            field
-            for field in ["gerrit_ssh_user_g2g", "gerrit_ssh_user_g2g_email"]
-            if not getattr(data, field)
+            field for field in ["gerrit_ssh_user_g2g", "gerrit_ssh_user_g2g_email"] if not getattr(data, field)
         ]
         if missing_gerrit_params:
             if data.organization:
@@ -915,7 +1162,7 @@ def _validate_inputs(data: Inputs) -> None:
                     ", ".join(missing_gerrit_params),
                 )
                 # Allow derivation in local mode only if explicitly enabled
-                if not _env_bool("G2G_ENABLE_DERIVATION", False):
+                if not env_bool("G2G_ENABLE_DERIVATION", False):
                     required_fields.extend(missing_gerrit_params)
             else:
                 required_fields.extend(missing_gerrit_params)
@@ -931,24 +1178,18 @@ def _validate_inputs(data: Inputs) -> None:
                     if is_github_actions:
                         log.error(
                             "These fields can be derived automatically from "
-                            "organization '%s'",
+                            "organization '%s' if G2G_ENABLE_DERIVATION=true",
                             data.organization,
                         )
                     else:
                         log.error(
-                            "These fields can be derived from organization "
-                            "'%s'",
+                            "These fields can be derived from organization '%s'",
                             data.organization,
                         )
                         log.error("Set G2G_ENABLE_DERIVATION=true to enable")
                 else:
-                    log.error(
-                        "These fields require either explicit values or an "
-                        "ORGANIZATION for derivation"
-                    )
-            raise ConfigurationError(
-                _MSG_MISSING_REQUIRED_INPUT.format(field_name=field_name)
-            )
+                    log.error("These fields require either explicit values or an ORGANIZATION for derivation")
+            raise ConfigurationError(_MSG_MISSING_REQUIRED_INPUT.format(field_name=field_name))
 
     # Validate fetch depth is a positive integer
     if data.fetch_depth <= 0:
@@ -967,9 +1208,7 @@ def _log_effective_config(data: Inputs, gh: GitHubContext) -> None:
     log.info("  SUBMIT_SINGLE_COMMITS: %s", data.submit_single_commits)
     log.info("  USE_PR_AS_COMMIT: %s", data.use_pr_as_commit)
     log.info("  FETCH_DEPTH: %s", data.fetch_depth)
-    known_hosts_status = (
-        "<provided>" if data.gerrit_known_hosts else "<will auto-discover>"
-    )
+    known_hosts_status = "<provided>" if data.gerrit_known_hosts else "<will auto-discover>"
     log.info("  GERRIT_KNOWN_HOSTS: %s", known_hosts_status)
     log.info("  GERRIT_SSH_PRIVKEY_G2G: %s", safe_privkey)
     log.info("  GERRIT_SSH_USER_G2G: %s", data.gerrit_ssh_user_g2g)
@@ -978,7 +1217,8 @@ def _log_effective_config(data: Inputs, gh: GitHubContext) -> None:
     log.info("  REVIEWERS_EMAIL: %s", data.reviewers_email or "")
     log.info("  PRESERVE_GITHUB_PRS: %s", data.preserve_github_prs)
     log.info("  DRY_RUN: %s", data.dry_run)
-    log.info("  GERRIT_SERVER: %s", data.gerrit_server or "")
+    log.info("  CI_TESTING: %s", data.ci_testing)
+    log.info("  GERRIT_SERVER: %s", data.gerrit_server)
     log.info("  GERRIT_SERVER_PORT: %s", data.gerrit_server_port or "")
     log.info("  GERRIT_PROJECT: %s", data.gerrit_project or "")
     log.info("GitHub context:")