github2gerrit 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

github2gerrit/core.py

@@ -29,6 +29,7 @@ from __future__ import annotations
 import logging
 import os
 import re
+import shlex
 import stat
 import urllib.parse
 import urllib.request
@@ -38,14 +39,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-
-try:
-    from pygerrit2 import GerritRestAPI
-    from pygerrit2 import HTTPBasicAuth
-except ImportError:
-    GerritRestAPI = None
-    HTTPBasicAuth = None
-
+from .gerrit_urls import create_gerrit_url_builder
 from .github_api import build_client
 from .github_api import close_pr
 from .github_api import create_pr_comment
@@ -67,9 +61,50 @@ from .models import GitHubContext
 from .models import Inputs
 
 
+try:
+    from pygerrit2 import GerritRestAPI
+    from pygerrit2 import HTTPBasicAuth
+except ImportError:
+    GerritRestAPI = None
+    HTTPBasicAuth = None
+
+try:
+    from .ssh_discovery import SSHDiscoveryError
+    from .ssh_discovery import auto_discover_gerrit_host_keys
+except ImportError:
+    # Fallback if ssh_discovery module is not available
+    auto_discover_gerrit_host_keys = None  # type: ignore[assignment]
+    SSHDiscoveryError = Exception  # type: ignore[misc,assignment]
+
+
+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)
+
+
 log = logging.getLogger("github2gerrit.core")
 
 
+# Error message constants to comply with TRY003
+_MSG_ISSUE_ID_MULTILINE = "Issue ID must be single line"
+_MSG_MISSING_PR_CONTEXT = "missing PR context"
+_MSG_BAD_REPOSITORY_CONTEXT = "bad repository context"
+_MSG_MISSING_GERRIT_SERVER = "missing GERRIT_SERVER"
+_MSG_MISSING_GERRIT_PROJECT = "missing GERRIT_PROJECT"
+_MSG_PYGERRIT2_REQUIRED_REST = "pygerrit2 is required to query Gerrit REST API"
+_MSG_PYGERRIT2_REQUIRED_AUTH = "pygerrit2 is required for HTTP authentication"
+_MSG_PYGERRIT2_MISSING = "pygerrit2 missing"
+_MSG_PYGERRIT2_AUTH_MISSING = "pygerrit2 auth missing"
+
+
 def _insert_issue_id_into_commit_message(message: str, issue_id: str) -> str:
     """
     Insert Issue ID into commit message after the first line.
@@ -87,13 +122,10 @@ def _insert_issue_id_into_commit_message(message: str, issue_id: str) -> str:
     # Validate that Issue ID is a single line string
     cleaned_issue_id = issue_id.strip()
     if "\n" in cleaned_issue_id or "\r" in cleaned_issue_id:
-        raise ValueError("Issue ID must be single line")  # noqa: TRY003
+        raise ValueError(_MSG_ISSUE_ID_MULTILINE)
 
     # Format as proper Issue-ID trailer
-    if cleaned_issue_id.startswith("Issue-ID:"):
-        issue_line = cleaned_issue_id
-    else:
-        issue_line = f"Issue-ID: {cleaned_issue_id}"
+    issue_line = cleaned_issue_id if cleaned_issue_id.startswith("Issue-ID:") else f"Issue-ID: {cleaned_issue_id}"
 
     lines = message.splitlines()
     if not lines:
@@ -228,14 +260,34 @@ class Orchestrator:
 
         if inputs.dry_run:
             # Perform preflight validations and exit without making changes
-            self._dry_run_preflight(
-                gerrit=gerrit, inputs=inputs, gh=gh, repo=repo_names
-            )
+            self._dry_run_preflight(gerrit=gerrit, inputs=inputs, gh=gh, repo=repo_names)
             log.info("Dry run complete; skipping write operations to Gerrit")
-            return SubmissionResult(
-                change_urls=[], change_numbers=[], commit_shas=[]
+            return SubmissionResult(change_urls=[], change_numbers=[], commit_shas=[])
+        self._setup_ssh(inputs, gerrit)
+        # Establish baseline non-interactive SSH/Git environment
+        # for all child processes
+        os.environ.update(self._ssh_env())
+
+        # Ensure commit/tag signing is disabled before any commit operations
+        # to avoid agent prompts
+        try:
+            git_config(
+                "commit.gpgsign",
+                "false",
+                global_=False,
+                cwd=self.workspace,
             )
-        self._setup_ssh(inputs)
+        except GitError:
+            git_config("commit.gpgsign", "false", global_=True)
+        try:
+            git_config(
+                "tag.gpgsign",
+                "false",
+                global_=False,
+                cwd=self.workspace,
+            )
+        except GitError:
+            git_config("tag.gpgsign", "false", global_=True)
 
         if inputs.submit_single_commits:
             prep = self._prepare_single_commits(inputs, gh, gerrit)
@@ -281,7 +333,7 @@ class Orchestrator:
 
     def _guard_pull_request_context(self, gh: GitHubContext) -> None:
         if gh.pr_number is None:
-            raise OrchestratorError("missing PR context")  # noqa: TRY003
+            raise OrchestratorError(_MSG_MISSING_PR_CONTEXT)
         log.debug("PR context OK: #%s", gh.pr_number)
 
     def _parse_gitreview_text(self, text: str) -> GerritInfo | None:
@@ -319,13 +371,8 @@ class Orchestrator:
                 repo_obj: Any = get_repo_from_env(client)
                 # Prefer a specific ref when available; otherwise default branch
                 ref = os.getenv("GITHUB_HEAD_REF") or os.getenv("GITHUB_SHA")
-                if ref:
-                    content = repo_obj.get_contents(".gitreview", ref=ref)
-                else:
-                    content = repo_obj.get_contents(".gitreview")
-                text_remote = (
-                    getattr(content, "decoded_content", b"") or b""
-                ).decode("utf-8")
+                content = repo_obj.get_contents(".gitreview", ref=ref) if ref else repo_obj.get_contents(".gitreview")
+                text_remote = (getattr(content, "decoded_content", b"") or b"").decode("utf-8")
                 info_remote = self._parse_gitreview_text(text_remote)
                 if info_remote:
                     log.debug("Parsed remote .gitreview: %s", info_remote)
@@ -335,14 +382,7 @@ class Orchestrator:
                 log.debug("Remote .gitreview not available: %s", exc)
             # Attempt raw.githubusercontent.com as a fallback
             try:
-                repo_full = (
-                    (
-                        gh.repository
-                        if gh
-                        else os.getenv("GITHUB_REPOSITORY", "")
-                    )
-                    or ""
-                ).strip()
+                repo_full = ((gh.repository if gh else os.getenv("GITHUB_REPOSITORY", "")) or "").strip()
                 branches: list[str] = []
                 # Prefer PR head/base refs via GitHub API when running
                 # from a direct URL when a token is available
@@ -356,18 +396,8 @@ class Orchestrator:
                         client = build_client()
                         repo_obj = get_repo_from_env(client)
                         pr_obj = get_pull(repo_obj, int(gh.pr_number))
-                        api_head = str(
-                            getattr(
-                                getattr(pr_obj, "head", object()), "ref", ""
-                            )
-                            or ""
-                        )
-                        api_base = str(
-                            getattr(
-                                getattr(pr_obj, "base", object()), "ref", ""
-                            )
-                            or ""
-                        )
+                        api_head = str(getattr(getattr(pr_obj, "head", object()), "ref", "") or "")
+                        api_base = str(getattr(getattr(pr_obj, "base", object()), "ref", "") or "")
                         if api_head:
                             branches.append(api_head)
                         if api_base:
@@ -387,15 +417,9 @@ class Orchestrator:
                     if not br or br in tried:
                         continue
                     tried.add(br)
-                    url = (
-                        f"https://raw.githubusercontent.com/"
-                        f"{repo_full}/refs/heads/{br}/.gitreview"
-                    )
+                    url = f"https://raw.githubusercontent.com/{repo_full}/refs/heads/{br}/.gitreview"
                     parsed = urllib.parse.urlparse(url)
-                    if (
-                        parsed.scheme != "https"
-                        or parsed.netloc != "raw.githubusercontent.com"
-                    ):
+                    if parsed.scheme != "https" or parsed.netloc != "raw.githubusercontent.com":
                         continue
                     log.info("Fetching .gitreview via raw URL: %s", url)
                     with urllib.request.urlopen(url, timeout=5) as resp:  # noqa: S310
@@ -446,7 +470,7 @@ class Orchestrator:
         # Fallback: use the repository name portion only.
         repo_full = gh.repository
         if not repo_full or "/" not in repo_full:
-            raise OrchestratorError("bad repository context")  # noqa: TRY003
+            raise OrchestratorError(_MSG_BAD_REPOSITORY_CONTEXT)
         owner, name = repo_full.split("/", 1)
         # Fallback: map all '-' to '/' for Gerrit path (e.g., 'my/repo/name')
         gerrit_name = name.replace("-", "/")
@@ -466,7 +490,7 @@ class Orchestrator:
 
         host = inputs.gerrit_server.strip()
         if not host:
-            raise OrchestratorError("missing GERRIT_SERVER")  # noqa: TRY003
+            raise OrchestratorError(_MSG_MISSING_GERRIT_SERVER)
         port_s = inputs.gerrit_server_port.strip() or "29418"
         try:
             port = int(port_s)
@@ -486,13 +510,13 @@ class Orchestrator:
                     project,
                 )
             else:
-                raise OrchestratorError("missing GERRIT_PROJECT")  # noqa: TRY003
+                raise OrchestratorError(_MSG_MISSING_GERRIT_PROJECT)
 
         info = GerritInfo(host=host, port=port, project=project)
         log.debug("Resolved Gerrit info: %s", info)
         return info
 
-    def _setup_ssh(self, inputs: Inputs) -> None:
+    def _setup_ssh(self, inputs: Inputs, gerrit: GerritInfo) -> None:
         """Set up temporary SSH configuration for Gerrit access.
 
         This method creates tool-specific SSH files in the workspace without
@@ -506,8 +530,35 @@ class Orchestrator:
 
         Does not modify user files.
         """
-        if not inputs.gerrit_ssh_privkey_g2g or not inputs.gerrit_known_hosts:
-            log.debug("SSH key or known hosts not provided, skipping SSH setup")
+        if not inputs.gerrit_ssh_privkey_g2g:
+            log.debug("SSH private key not provided, skipping SSH setup")
+            return
+
+        # Auto-discover host keys if not provided
+        effective_known_hosts = inputs.gerrit_known_hosts
+        if not effective_known_hosts and auto_discover_gerrit_host_keys is not None:
+            log.info("GERRIT_KNOWN_HOSTS not provided, attempting auto-discovery...")
+            try:
+                discovered_keys = auto_discover_gerrit_host_keys(
+                    gerrit_hostname=gerrit.host,
+                    gerrit_port=gerrit.port,
+                    organization=inputs.organization,
+                    save_to_config=True,
+                )
+                if discovered_keys:
+                    effective_known_hosts = discovered_keys
+                    log.info(
+                        "Successfully auto-discovered SSH host keys for %s:%d",
+                        gerrit.host,
+                        gerrit.port,
+                    )
+                else:
+                    log.warning("Auto-discovery failed, SSH host key verification may fail")
+            except Exception as exc:
+                log.warning("SSH host key auto-discovery failed: %s", exc)
+
+        if not effective_known_hosts:
+            log.debug("No SSH host keys available (manual or auto-discovered), skipping SSH setup")
             return
 
         log.info("Setting up temporary SSH configuration for Gerrit")
@@ -529,7 +580,7 @@ class Orchestrator:
         # Write known hosts to tool-specific location
         known_hosts_path = tool_ssh_dir / "known_hosts"
         with open(known_hosts_path, "w", encoding="utf-8") as f:
-            f.write(inputs.gerrit_known_hosts.strip() + "\n")
+            f.write(effective_known_hosts.strip() + "\n")
         known_hosts_path.chmod(0o644)
         log.debug("Known hosts written to %s", known_hosts_path)
         log.debug("Using isolated known_hosts to prevent user conflicts")
@@ -551,9 +602,13 @@ class Orchestrator:
 
         # Build SSH command with strict options to prevent key scanning
         ssh_options = [
+            "-F /dev/null",
             f"-i {self._ssh_key_path}",
             f"-o UserKnownHostsFile={self._ssh_known_hosts_path}",
             "-o IdentitiesOnly=yes",  # Critical: prevents SSH agent scanning
+            "-o IdentityAgent=none",
+            "-o BatchMode=yes",
+            "-o PreferredAuthentications=publickey",
             "-o StrictHostKeyChecking=yes",
             "-o PasswordAuthentication=no",
             "-o PubkeyAcceptedKeyTypes=+ssh-rsa",
@@ -565,15 +620,35 @@ class Orchestrator:
         log.debug("Generated SSH command: %s", masked_cmd)
         return ssh_cmd
 
+    def _ssh_env(self) -> dict[str, str]:
+        """Centralized non-interactive SSH/Git environment."""
+        cmd = self._git_ssh_command or (
+            "ssh -F /dev/null "
+            "-o IdentitiesOnly=yes "
+            "-o IdentityAgent=none "
+            "-o BatchMode=yes "
+            "-o PreferredAuthentications=publickey "
+            "-o StrictHostKeyChecking=yes "
+            "-o PasswordAuthentication=no "
+            "-o PubkeyAcceptedKeyTypes=+ssh-rsa "
+            "-o ConnectTimeout=10"
+        )
+        return {
+            "GIT_SSH_COMMAND": cmd,
+            "SSH_AUTH_SOCK": "",
+            "SSH_AGENT_PID": "",
+            "SSH_ASKPASS": "/usr/bin/false",
+            "DISPLAY": "",
+            "SSH_ASKPASS_REQUIRE": "never",
+        }
+
     def _cleanup_ssh(self) -> None:
         """Clean up temporary SSH files created by this tool.
 
         Removes the workspace-specific .ssh-g2g directory and all contents.
         This ensures no temporary files are left behind.
         """
-        if not hasattr(self, "_ssh_key_path") or not hasattr(
-            self, "_ssh_known_hosts_path"
-        ):
+        if not hasattr(self, "_ssh_key_path") or not hasattr(self, "_ssh_known_hosts_path"):
             return
 
         try:
@@ -583,9 +658,7 @@ class Orchestrator:
                 import shutil
 
                 shutil.rmtree(tool_ssh_dir)
-                log.debug(
-                    "Cleaned up temporary SSH directory: %s", tool_ssh_dir
-                )
+                log.debug("Cleaned up temporary SSH directory: %s", tool_ssh_dir)
         except Exception as exc:
             log.warning("Failed to clean up temporary SSH files: %s", exc)
 
@@ -605,9 +678,7 @@ class Orchestrator:
                 cwd=self.workspace,
             )
         except GitError:
-            git_config(
-                "gitreview.username", inputs.gerrit_ssh_user_g2g, global_=True
-            )
+            git_config("gitreview.username", inputs.gerrit_ssh_user_g2g, global_=True)
         try:
             git_config(
                 "user.name",
@@ -625,9 +696,26 @@ class Orchestrator:
                 cwd=self.workspace,
             )
         except GitError:
+            git_config("user.email", inputs.gerrit_ssh_user_g2g_email, global_=True)
+        # Disable GPG signing to avoid interactive prompts for signing keys
+        try:
             git_config(
-                "user.email", inputs.gerrit_ssh_user_g2g_email, global_=True
+                "commit.gpgsign",
+                "false",
+                global_=False,
+                cwd=self.workspace,
             )
+        except GitError:
+            git_config("commit.gpgsign", "false", global_=True)
+        try:
+            git_config(
+                "tag.gpgsign",
+                "false",
+                global_=False,
+                cwd=self.workspace,
+            )
+        except GitError:
+            git_config("tag.gpgsign", "false", global_=True)
 
         # Ensure git-review host/port/project are configured
         # when .gitreview is absent
@@ -663,16 +751,10 @@ class Orchestrator:
             )
         except CommandError:
             ssh_user = inputs.gerrit_ssh_user_g2g.strip()
-            remote_url = (
-                f"ssh://{ssh_user}@{gerrit.host}:{gerrit.port}/{gerrit.project}"
-            )
+            remote_url = f"ssh://{ssh_user}@{gerrit.host}:{gerrit.port}/{gerrit.project}"
             log.info("Adding 'gerrit' remote: %s", remote_url)
             # Use our specific SSH configuration for adding remote
-            env = (
-                {"GIT_SSH_COMMAND": self._git_ssh_command}
-                if self._git_ssh_command
-                else None
-            )
+            env = self._ssh_env()
             run_cmd(
                 ["git", "remote", "add", "gerrit", remote_url],
                 check=False,
@@ -681,9 +763,7 @@ class Orchestrator:
             )
 
         # Workaround for submodules commit-msg hook
-        hooks_path = run_cmd(
-            ["git", "rev-parse", "--show-toplevel"], cwd=self.workspace
-        ).stdout.strip()
+        hooks_path = run_cmd(["git", "rev-parse", "--show-toplevel"], cwd=self.workspace).stdout.strip()
         try:
             git_config(
                 "core.hooksPath",
@@ -699,11 +779,7 @@ class Orchestrator:
         # Initialize git-review (copies commit-msg hook)
         try:
             # Use our specific SSH configuration for git-review setup
-            env = (
-                {"GIT_SSH_COMMAND": self._git_ssh_command}
-                if self._git_ssh_command
-                else None
-            )
+            env = self._ssh_env()
             run_cmd(["git", "review", "-s", "-v"], cwd=self.workspace, env=env)
         except CommandError as exc:
             msg = f"Failed to initialize git-review: {exc}"
@@ -721,12 +797,12 @@ class Orchestrator:
         # Determine commit range: commits in HEAD not in base branch
         base_ref = f"origin/{branch}"
         # Use our SSH command for git operations that might need SSH
-        env = (
-            {"GIT_SSH_COMMAND": self._git_ssh_command}
-            if self._git_ssh_command
-            else None
+
+        run_cmd(
+            ["git", "fetch", "origin", branch],
+            cwd=self.workspace,
+            env=self._ssh_env(),
         )
-        run_cmd(["git", "fetch", "origin", branch], cwd=self.workspace, env=env)
         revs = run_cmd(
             ["git", "rev-list", "--reverse", f"{base_ref}..HEAD"],
             cwd=self.workspace,
@@ -736,14 +812,10 @@ class Orchestrator:
             log.info("No commits to submit; returning empty PreparedChange")
             return PreparedChange(change_ids=[], commit_shas=[])
         # Create temp branch from base sha; export for downstream
-        base_sha = run_cmd(
-            ["git", "rev-parse", base_ref], cwd=self.workspace
-        ).stdout.strip()
+        base_sha = run_cmd(["git", "rev-parse", base_ref], cwd=self.workspace).stdout.strip()
         tmp_branch = f"g2g_tmp_{gh.pr_number or 'pr'!s}_{os.getpid()}"
         os.environ["G2G_TMP_BRANCH"] = tmp_branch
-        run_cmd(
-            ["git", "checkout", "-b", tmp_branch, base_sha], cwd=self.workspace
-        )
+        run_cmd(["git", "checkout", "-b", tmp_branch, base_sha], cwd=self.workspace)
         change_ids: list[str] = []
         for csha in commit_list:
             run_cmd(["git", "checkout", tmp_branch], cwd=self.workspace)
@@ -753,13 +825,9 @@ class Orchestrator:
                 ["git", "show", "-s", "--pretty=format:%an <%ae>", csha],
                 cwd=self.workspace,
             ).stdout.strip()
-            git_commit_amend(
-                author=author, no_edit=True, signoff=True, cwd=self.workspace
-            )
+            git_commit_amend(author=author, no_edit=True, signoff=True, cwd=self.workspace)
             # Extract newly added Change-Id from last commit trailers
-            trailers = git_last_commit_trailers(
-                keys=["Change-Id"], cwd=self.workspace
-            )
+            trailers = git_last_commit_trailers(keys=["Change-Id"], cwd=self.workspace)
             for cid in trailers.get("Change-Id", []):
                 if cid:
                     change_ids.append(cid)
@@ -793,26 +861,20 @@ class Orchestrator:
         """Squash PR commits into a single commit and handle Change-Id."""
         log.info("Preparing squashed commit for PR #%s", gh.pr_number)
         branch = self._resolve_target_branch()
-        env = (
-            {"GIT_SSH_COMMAND": self._git_ssh_command}
-            if self._git_ssh_command
-            else None
+
+        run_cmd(
+            ["git", "fetch", "origin", branch],
+            cwd=self.workspace,
+            env=self._ssh_env(),
         )
-        run_cmd(["git", "fetch", "origin", branch], cwd=self.workspace, env=env)
         base_ref = f"origin/{branch}"
-        base_sha = run_cmd(
-            ["git", "rev-parse", base_ref], cwd=self.workspace
-        ).stdout.strip()
-        head_sha = run_cmd(
-            ["git", "rev-parse", "HEAD"], cwd=self.workspace
-        ).stdout.strip()
+        base_sha = run_cmd(["git", "rev-parse", base_ref], cwd=self.workspace).stdout.strip()
+        head_sha = run_cmd(["git", "rev-parse", "HEAD"], cwd=self.workspace).stdout.strip()
 
         # Create temp branch from base and merge-squash PR head
         tmp_branch = f"g2g_tmp_{gh.pr_number or 'pr'!s}_{os.getpid()}"
         os.environ["G2G_TMP_BRANCH"] = tmp_branch
-        run_cmd(
-            ["git", "checkout", "-b", tmp_branch, base_sha], cwd=self.workspace
-        )
+        run_cmd(["git", "checkout", "-b", tmp_branch, base_sha], cwd=self.workspace)
         run_cmd(["git", "merge", "--squash", head_sha], cwd=self.workspace)
 
         def _collect_log_lines() -> list[str]:
@@ -840,18 +902,13 @@ class Orchestrator:
             message_lines: list[str] = []
             in_metadata_section = False
             for ln in lines:
-                if ln.strip() in ("---", "```") or ln.startswith(
-                    "updated-dependencies:"
-                ):
+                if ln.strip() in ("---", "```") or ln.startswith("updated-dependencies:"):
                     in_metadata_section = True
                     continue
                 if in_metadata_section:
                     if ln.startswith(("- dependency-", "  dependency-")):
                         continue
-                    if (
-                        not ln.startswith(("  ", "-", "dependency-"))
-                        and ln.strip()
-                    ):
+                    if not ln.startswith(("  ", "-", "dependency-")) and ln.strip():
                         in_metadata_section = False
                 if ln.startswith("Change-Id:"):
                     cid = ln.split(":", 1)[1].strip()
@@ -882,17 +939,11 @@ class Orchestrator:
                 break_points = [". ", "! ", "? ", " - ", ": "]
                 for bp in break_points:
                     if bp in title_line[:100]:
-                        title_line = title_line[
-                            : title_line.index(bp) + len(bp.strip())
-                        ]
+                        title_line = title_line[: title_line.index(bp) + len(bp.strip())]
                         break
                 else:
                     words = title_line[:100].split()
-                    title_line = (
-                        " ".join(words[:-1])
-                        if len(words) > 1
-                        else title_line[:100].rstrip()
-                    )
+                    title_line = " ".join(words[:-1]) if len(words) > 1 else title_line[:100].rstrip()
             return title_line
 
         def _build_clean_message_lines(message_lines: list[str]) -> list[str]:
@@ -902,10 +953,7 @@ class Orchestrator:
             out: list[str] = [title_line]
             if len(message_lines) > 1:
                 body_start = 1
-                while (
-                    body_start < len(message_lines)
-                    and not message_lines[body_start].strip()
-                ):
+                while body_start < len(message_lines) and not message_lines[body_start].strip():
                     body_start += 1
                 if body_start < len(message_lines):
                     out.append("")
@@ -914,9 +962,7 @@ class Orchestrator:
 
         def _maybe_reuse_change_id(pr_str: str) -> str:
             reuse = ""
-            sync_all_prs = (
-                os.getenv("SYNC_ALL_OPEN_PRS", "false").lower() == "true"
-            )
+            sync_all_prs = os.getenv("SYNC_ALL_OPEN_PRS", "false").lower() == "true"
             if (
                 not sync_all_prs
                 and gh.event_name == "pull_request_target"
@@ -926,9 +972,7 @@ class Orchestrator:
                     client = build_client()
                     repo = get_repo_from_env(client)
                     pr_obj = get_pull(repo, int(pr_str))
-                    cand = get_recent_change_ids_from_comments(
-                        pr_obj, max_comments=50
-                    )
+                    cand = get_recent_change_ids_from_comments(pr_obj, max_comments=50)
                     if cand:
                         reuse = cand[-1]
                         log.debug(
@@ -950,12 +994,8 @@ class Orchestrator:
             signed_off: list[str],
             reuse_cid: str,
         ) -> str:
-            from .duplicate_detection import DuplicateDetector
-
             msg = "\n".join(lines_in).strip()
             msg = _insert_issue_id_into_commit_message(msg, inputs.issue_id)
-            github_hash = DuplicateDetector._generate_github_change_hash(gh)
-            msg += f"\n\nGitHub-Hash: {github_hash}"
             if signed_off:
                 msg += "\n\n" + "\n".join(signed_off)
             if reuse_cid:
@@ -964,9 +1004,7 @@ class Orchestrator:
 
         # Build message parts
         raw_lines = _collect_log_lines()
-        message_lines, signed_off, _existing_cids = _parse_message_parts(
-            raw_lines
-        )
+        message_lines, signed_off, _existing_cids = _parse_message_parts(raw_lines)
         clean_lines = _build_clean_message_lines(message_lines)
         pr_str = str(gh.pr_number or "").strip()
         reuse_cid = _maybe_reuse_change_id(pr_str)
@@ -1040,29 +1078,51 @@ class Orchestrator:
             title = re.sub(r"[*_`]", "", title)
             title = title.strip()
 
-        # Compose message; preserve any Signed-off-by lines
-        current_body = git_show("HEAD", fmt="%B")
-        signed = [
-            ln
-            for ln in current_body.splitlines()
-            if ln.startswith("Signed-off-by:")
-        ]
+        # Compose message; preserve existing trailers at footer
+        # (Signed-off-by, Change-Id)
+        current_body = git_show("HEAD", fmt="%B", cwd=self.workspace)
+        # Extract existing trailers from current commit body
+        lines_cur = current_body.splitlines()
+        signed_lines = [ln for ln in lines_cur if ln.startswith("Signed-off-by:")]
+        change_id_lines = [ln for ln in lines_cur if ln.startswith("Change-Id:")]
+        github_hash_lines = [ln for ln in lines_cur if ln.startswith("GitHub-Hash:")]
+
         msg_parts = [title, "", body] if title or body else [current_body]
         commit_message = "\n".join(msg_parts).strip()
 
         # Add Issue-ID if provided
-        commit_message = _insert_issue_id_into_commit_message(
-            commit_message, inputs.issue_id
-        )
+        commit_message = _insert_issue_id_into_commit_message(commit_message, inputs.issue_id)
+
+        # Ensure GitHub-Hash is part of the body (not trailers)
+        # to keep a blank line before Signed-off-by/Change-Id trailers.
+        if github_hash_lines:
+            gh_hash_line = github_hash_lines[-1]
+        else:
+            from .duplicate_detection import DuplicateDetector
+
+            gh_val = DuplicateDetector._generate_github_change_hash(gh)
+            gh_hash_line = f"GitHub-Hash: {gh_val}"
+
+        commit_message += "\n\n" + gh_hash_line
+
+        # Build trailers: Signed-off-by first, Change-Id last.
+        trailers_out: list[str] = []
+        if signed_lines:
+            trailers_out.extend(signed_lines)
+        if change_id_lines:
+            trailers_out.append(change_id_lines[-1])
+        if trailers_out:
+            commit_message += "\n\n" + "\n".join(trailers_out)
 
-        if signed:
-            commit_message += "\n\n" + "\n".join(signed)
         author = run_cmd(
-            ["git", "show", "-s", "--pretty=format:%an <%ae>", "HEAD"]
+            ["git", "show", "-s", "--pretty=format:%an <%ae>", "HEAD"],
+            cwd=self.workspace,
+            env=self._ssh_env(),
         ).stdout.strip()
         git_commit_amend(
+            cwd=self.workspace,
             no_edit=False,
-            signoff=not bool(signed),
+            signoff=not bool(signed_lines),
             author=author,
             message=commit_message,
         )
@@ -1090,10 +1150,7 @@ class Orchestrator:
             run_cmd(["git", "checkout", tmp_branch], cwd=self.workspace)
         prefix = os.getenv("G2G_TOPIC_PREFIX", "GH").strip() or "GH"
         pr_num = os.getenv("PR_NUMBER", "").strip()
-        if pr_num:
-            topic = f"{prefix}-{repo.project_github}-{pr_num}"
-        else:
-            topic = f"{prefix}-{repo.project_github}"
+        topic = f"{prefix}-{repo.project_github}-{pr_num}" if pr_num else f"{prefix}-{repo.project_github}"
         try:
             args = [
                 "git",
@@ -1103,31 +1160,22 @@ class Orchestrator:
                 "-t",
                 topic,
             ]
-            revs = [
-                r.strip() for r in (reviewers or "").split(",") if r.strip()
-            ]
+            revs = [r.strip() for r in (reviewers or "").split(",") if r.strip()]
             for r in revs:
                 args.extend(["--reviewer", r])
             # Branch as positional argument (not a flag)
             args.append(branch)
 
             # Use our specific SSH configuration
-            env = (
-                {"GIT_SSH_COMMAND": self._git_ssh_command}
-                if self._git_ssh_command
-                else None
-            )
+            env = self._ssh_env()
             log.debug("Executing git review command: %s", " ".join(args))
             run_cmd(args, cwd=self.workspace, env=env)
             log.info("Successfully pushed changes to Gerrit")
         except CommandError as exc:
             # Analyze the specific failure reason from git review output
             error_details = self._analyze_gerrit_push_failure(exc)
-            log.exception("Gerrit push failed: %s", error_details)
-            msg = (
-                f"Failed to push changes to Gerrit with git-review: "
-                f"{error_details}"
-            )
+            _log_exception_conditionally(log, "Gerrit push failed: %s", error_details)
+            msg = f"Failed to push changes to Gerrit with git-review: {error_details}"
             raise OrchestratorError(msg) from exc
         # Cleanup temporary branch used during preparation
         tmp_branch = (os.getenv("G2G_TMP_BRANCH", "") or "").strip()
@@ -1137,11 +1185,13 @@ class Orchestrator:
                 ["git", "checkout", f"origin/{branch}"],
                 check=False,
                 cwd=self.workspace,
+                env=env,
             )
             run_cmd(
                 ["git", "branch", "-D", tmp_branch],
                 check=False,
                 cwd=self.workspace,
+                env=env,
             )
 
     def _analyze_gerrit_push_failure(self, exc: CommandError) -> str:
@@ -1151,14 +1201,60 @@ class Orchestrator:
         combined_output = f"{stdout}\n{stderr}"
         combined_lower = combined_output.lower()
 
-        if "missing issue-id" in combined_lower:
+        # Check for SSH host key verification failures first
+        if (
+            "host key verification failed" in combined_lower
+            or "no ed25519 host key is known" in combined_lower
+            or "no rsa host key is known" in combined_lower
+            or "no ecdsa host key is known" in combined_lower
+        ):
+            return (
+                "SSH host key verification failed. The GERRIT_KNOWN_HOSTS "
+                "value is missing or contains an outdated host key for the "
+                "Gerrit server. The tool will attempt to auto-discover "
+                "host keys "
+                "on the next run, or you can manually run "
+                "'ssh-keyscan -p 29418 <gerrit-host>' "
+                "to get the current host keys."
+            )
+        elif "authenticity of host" in combined_lower and "can't be established" in combined_lower:
+            return (
+                "SSH host key unknown. The GERRIT_KNOWN_HOSTS value does not "
+                "contain the host key for the Gerrit server. "
+                "The tool will attempt "
+                "to auto-discover host keys on the next run, or you can "
+                "manually run "
+                "'ssh-keyscan -p 29418 <gerrit-host>' to get the host keys."
+            )
+        # Check for specific SSH key issues before general permission denied
+        elif "key_load_public" in combined_lower and "invalid format" in combined_lower:
+            return "SSH key format is invalid. Check that the SSH private key is properly formatted."
+        elif "no matching host key type found" in combined_lower:
+            return "SSH key type not supported by server. The server may not accept this SSH key algorithm."
+        elif "authentication failed" in combined_lower:
+            return "SSH authentication failed - check SSH key, username, and server configuration"
+        # Check for connection timeout/refused before "could not read" check
+        elif "connection timed out" in combined_lower or "connection refused" in combined_lower:
+            return "Connection failed - check network connectivity and Gerrit server availability"
+        # Check for specific SSH publickey-only authentication failures
+        elif "permission denied (publickey)" in combined_lower and not any(
+            auth_method in combined_lower for auth_method in ["gssapi", "password", "keyboard"]
+        ):
+            return (
+                "SSH public key authentication failed. The SSH key may be "
+                "invalid, not authorized for this user, or the wrong key type."
+            )
+        # Check for general SSH permission issues
+        elif "permission denied" in combined_lower:
+            return "SSH permission denied - check SSH key and user permissions"
+        elif "could not read from remote repository" in combined_lower:
+            return "Could not read from remote repository - check SSH authentication and repository access permissions"
+        # Check for Gerrit-specific issues
+        elif "missing issue-id" in combined_lower:
             return "Missing Issue-ID in commit message."
         elif "commit not associated to any issue" in combined_lower:
             return "Commit not associated to any issue."
-        elif (
-            "remote rejected" in combined_lower
-            and "refs/for/" in combined_lower
-        ):
+        elif "remote rejected" in combined_lower and "refs/for/" in combined_lower:
             # Extract specific rejection reason from output
             lines = combined_output.split("\n")
             for line in lines:
@@ -1169,15 +1265,6 @@ class Orchestrator:
                         return f"Gerrit rejected the push: {reason}"
                     return f"Gerrit rejected the push: {line.strip()}"
             return "Gerrit rejected the push for an unknown reason"
-        elif "permission denied" in combined_lower:
-            return "Permission denied - check SSH key and user permissions"
-        elif "connection" in combined_lower and (
-            "refused" in combined_lower or "timeout" in combined_lower
-        ):
-            return (
-                "Connection failed - check network connectivity and "
-                "Gerrit server availability"
-            )
         else:
             return f"Unknown error: {exc}"
 
@@ -1190,32 +1277,28 @@ class Orchestrator:
     ) -> SubmissionResult:
         """Query Gerrit for change URL/number and patchset sha via REST."""
         log.info("Querying Gerrit for submitted change(s) via REST")
-        # Build Gerrit REST client (prefer HTTP basic auth if provided)
-        base_path = os.getenv("GERRIT_HTTP_BASE_PATH", "").strip().strip("/")
-        base_url = (
-            f"https://{gerrit.host}/"
-            if not base_path
-            else f"https://{gerrit.host}/{base_path}/"
-        )
-        http_user = (
-            os.getenv("GERRIT_HTTP_USER", "").strip()
-            or os.getenv("GERRIT_SSH_USER_G2G", "").strip()
-        )
+
+        # Create centralized URL builder
+        url_builder = create_gerrit_url_builder(gerrit.host)
+
+        # Get authentication credentials
+        http_user = os.getenv("GERRIT_HTTP_USER", "").strip() or os.getenv("GERRIT_SSH_USER_G2G", "").strip()
         http_pass = os.getenv("GERRIT_HTTP_PASSWORD", "").strip()
+
+        # Build Gerrit REST client (prefer HTTP basic auth if provided)
         if GerritRestAPI is None:
-            raise OrchestratorError(  # noqa: TRY003
-                "pygerrit2 is required to query Gerrit REST API"
-            )
-        if http_user and http_pass:
-            if HTTPBasicAuth is None:
-                raise OrchestratorError(  # noqa: TRY003
-                    "pygerrit2 is required for HTTP authentication"
-                )
-            rest = GerritRestAPI(
-                url=base_url, auth=HTTPBasicAuth(http_user, http_pass)
-            )
-        else:
-            rest = GerritRestAPI(url=base_url)
+            raise OrchestratorError(_MSG_PYGERRIT2_REQUIRED_REST)
+
+        def _create_rest_client(base_url: str) -> Any:
+            """Helper to create REST client with optional auth."""
+            if http_user and http_pass:
+                if HTTPBasicAuth is None:
+                    raise OrchestratorError(_MSG_PYGERRIT2_REQUIRED_AUTH)
+                return GerritRestAPI(url=base_url, auth=HTTPBasicAuth(http_user, http_pass))
+            else:
+                return GerritRestAPI(url=base_url)
+
+        # Try API URLs in order of preference (client creation happens in retry loop)
         urls: list[str] = []
         nums: list[str] = []
         shas: list[str] = []
@@ -1226,56 +1309,44 @@ class Orchestrator:
             # include current revision
             query = f"limit:1 is:open project:{repo.project_gerrit} {cid}"
             path = f"/changes/?q={query}&o=CURRENT_REVISION&n=1"
-            try:
-                changes = rest.get(path)
-            except Exception as exc:
-                status = getattr(
-                    getattr(exc, "response", None), "status_code", None
-                )
-                if not base_path and status == 404:
-                    try:
-                        fallback_url = f"https://{gerrit.host}/r/"
-                        if GerritRestAPI is None:
-                            log.warning(
-                                "pygerrit2 missing; skipping REST fallback"
-                            )
-                            continue
-                        if http_user and http_pass:
-                            if HTTPBasicAuth is None:
-                                log.warning(
-                                    "pygerrit2 auth missing; skipping fallback"
-                                )
-                                continue
-                            rest_fallback = GerritRestAPI(
-                                url=fallback_url,
-                                auth=HTTPBasicAuth(http_user, http_pass),
-                            )
-                        else:
-                            rest_fallback = GerritRestAPI(url=fallback_url)
-                        changes = rest_fallback.get(path)
-                    except Exception as exc2:
-                        log.warning(
-                            "Failed to query change via REST for %s "
-                            "(including '/r' fallback): %s",
-                            cid,
-                            exc2,
-                        )
-                        continue
-                else:
-                    log.warning(
-                        "Failed to query change via REST for %s: %s", cid, exc
-                    )
+            # Try API URLs in order of preference (handles fallbacks automatically)
+            api_candidates = url_builder.get_api_url_candidates(path)
+            changes = None
+            last_error = None
+
+            for api_url in api_candidates:
+                try:
+                    # Create a new client for each URL attempt
+                    current_rest = _create_rest_client(api_url.rsplit(path, 1)[0])
+                    changes = current_rest.get(path)
+                    break  # Success, exit the retry loop
+                except Exception as exc:
+                    last_error = exc
+                    log.debug("Failed API attempt for %s at %s: %s", cid, api_url, exc)
                     continue
+
+            if changes is None:
+                log.warning(
+                    "Failed to query change via REST for %s (tried %d URLs): %s",
+                    cid,
+                    len(api_candidates),
+                    last_error,
+                )
+                continue
             if not changes:
                 continue
             change = changes[0]
-            num = str(change.get("_number", ""))
-            current_rev = change.get("current_revision", "")
+            # Type guard to ensure mapping-like before dict access
+            if isinstance(change, dict):
+                num = str(change.get("_number", ""))
+                current_rev = change.get("current_revision", "")
+            else:
+                # Unexpected type; skip this result
+                continue
             # Construct a stable web URL for the change
             if num:
-                urls.append(
-                    f"https://{gerrit.host}/c/{repo.project_gerrit}/+/{num}"
-                )
+                change_url = url_builder.change_url(repo.project_gerrit, int(num))
+                urls.append(change_url)
                 nums.append(num)
             if current_rev:
                 shas.append(current_rev)
@@ -1286,9 +1357,7 @@ class Orchestrator:
             os.environ["GERRIT_CHANGE_REQUEST_NUM"] = "\n".join(nums)
         if shas:
             os.environ["GERRIT_COMMIT_SHA"] = "\n".join(shas)
-        return SubmissionResult(
-            change_urls=urls, change_numbers=nums, commit_shas=shas
-        )
+        return SubmissionResult(change_urls=urls, change_numbers=nums, commit_shas=shas)
 
     def _setup_git_workspace(self, inputs: Inputs, gh: GitHubContext) -> None:
         """Initialize and set up git workspace for PR processing."""
@@ -1309,10 +1378,7 @@ class Orchestrator:
 
         # Fetch PR head
         if gh.pr_number:
-            pr_ref = (
-                f"refs/pull/{gh.pr_number}/head:"
-                f"refs/remotes/origin/pr/{gh.pr_number}/head"
-            )
+            pr_ref = f"refs/pull/{gh.pr_number}/head:refs/remotes/origin/pr/{gh.pr_number}/head"
             run_cmd(
                 [
                     "git",
@@ -1341,13 +1407,48 @@ class Orchestrator:
         # Download commit-msg hook using SSH
         try:
             # Use curl to download the hook (more reliable than scp)
-            curl_cmd = [
-                "curl",
-                "-o",
-                str(hook_path),
-                f"https://{gerrit.host}/r/tools/hooks/commit-msg",
-            ]
-            run_cmd(curl_cmd, cwd=self.workspace)
+            # Create centralized URL builder for hook URLs
+            url_builder = create_gerrit_url_builder(gerrit.host)
+            candidates = url_builder.get_hook_url_candidates("commit-msg")
+
+            last_error = ""
+            installed = False
+            for candidate_url in candidates:
+                try:
+                    curl_cmd = [
+                        "curl",
+                        "-fL",
+                        "-o",
+                        str(hook_path),
+                        candidate_url,
+                    ]
+                    run_cmd(curl_cmd, cwd=self.workspace)
+                    # Make hook executable
+                    hook_path.chmod(hook_path.stat().st_mode | stat.S_IEXEC)
+                    log.debug(
+                        "Successfully installed commit-msg hook from %s",
+                        candidate_url,
+                    )
+                    installed = True
+                    break
+                except Exception as exc2:
+                    last_error = f"{candidate_url}: {exc2}"
+                    log.debug(
+                        "Failed to fetch commit-msg hook from %s: %s",
+                        candidate_url,
+                        exc2,
+                    )
+
+            def _raise_install_error() -> None:
+                raise RuntimeError("Hook install failed")  # noqa: TRY301, TRY003
+
+            if not installed:
+                # Log detailed reason separately to satisfy linting rules
+                log.error(
+                    "All commit-msg hook URLs failed. Last error: %s",
+                    last_error,
+                )
+                _raise_install_error()
 
             # Make hook executable
             hook_path.chmod(hook_path.stat().st_mode | stat.S_IEXEC)
@@ -1358,34 +1459,55 @@ class Orchestrator:
             msg = f"Could not install commit-msg hook: {exc}"
             raise OrchestratorError(msg) from exc
 
-    def _ensure_change_id_present(
-        self, gerrit: GerritInfo, author: str
-    ) -> list[str]:
+    def _ensure_change_id_present(self, gerrit: GerritInfo, author: str) -> list[str]:
         """Ensure the last commit has a Change-Id.
 
         Installs the commit-msg hook and amends the commit if needed.
         """
-        trailers = git_last_commit_trailers(
-            keys=["Change-Id"], cwd=self.workspace
-        )
+        trailers = git_last_commit_trailers(keys=["Change-Id"], cwd=self.workspace)
         if not trailers.get("Change-Id"):
-            log.debug(
-                "No Change-Id found, installing commit-msg hook and amending "
-                "commit"
-            )
-            self._install_commit_msg_hook(gerrit)
-            git_commit_amend(
-                no_edit=True, signoff=True, author=author, cwd=self.workspace
-            )
+            log.debug("No Change-Id found; attempting to install commit-msg hook and amend commit")
+            try:
+                self._install_commit_msg_hook(gerrit)
+                git_commit_amend(
+                    no_edit=True,
+                    signoff=True,
+                    author=author,
+                    cwd=self.workspace,
+                )
+            except Exception as exc:
+                log.warning(
+                    "Commit-msg hook installation failed, falling back to direct Change-Id injection: %s",
+                    exc,
+                )
+                # Fallback: generate a Change-Id and append to the commit
+                # message directly
+                import time
+
+                current_msg = run_cmd(
+                    ["git", "show", "-s", "--pretty=format:%B", "HEAD"],
+                    cwd=self.workspace,
+                ).stdout
+                seed = f"{current_msg}\n{time.time()}"
+                import hashlib as _hashlib  # local alias to satisfy linters
+
+                change_id = "I" + _hashlib.sha256(seed.encode("utf-8")).hexdigest()[:40]
+                if "Change-Id:" not in current_msg:
+                    new_msg = current_msg.rstrip() + "\n\n" + f"Change-Id: {change_id}\n"
+                    git_commit_amend(
+                        no_edit=False,
+                        signoff=True,
+                        author=author,
+                        message=new_msg,
+                        cwd=self.workspace,
+                    )
             # Debug: Check commit message after amend
             actual_msg = run_cmd(
                 ["git", "show", "-s", "--pretty=format:%B", "HEAD"],
                 cwd=self.workspace,
             ).stdout.strip()
             log.debug("Commit message after amend:\n%s", actual_msg)
-            trailers = git_last_commit_trailers(
-                keys=["Change-Id"], cwd=self.workspace
-            )
+            trailers = git_last_commit_trailers(keys=["Change-Id"], cwd=self.workspace)
         return [c for c in trailers.get("Change-Id", []) if c]
 
     def _add_backref_comment_in_gerrit(
@@ -1408,21 +1530,14 @@ class Orchestrator:
             "1",
             "yes",
         ):
-            log.info(
-                "Skipping back-reference comments "
-                "(G2G_SKIP_GERRIT_COMMENTS=true)"
-            )
+            log.info("Skipping back-reference comments (G2G_SKIP_GERRIT_COMMENTS=true)")
             return
 
         log.info("Adding back-reference comment in Gerrit")
         user = os.getenv("GERRIT_SSH_USER_G2G", "")
         server = gerrit.host
         pr_url = f"{gh.server_url}/{gh.repository}/pull/{gh.pr_number}"
-        run_url = (
-            f"{gh.server_url}/{gh.repository}/actions/runs/{gh.run_id}"
-            if gh.run_id
-            else "N/A"
-        )
+        run_url = f"{gh.server_url}/{gh.repository}/actions/runs/{gh.run_id}" if gh.run_id else "N/A"
         message = f"GHPR: {pr_url} | Action-Run: {run_url}"
         log.info("Adding back-reference comment: %s", message)
         for csha in commit_shas:
@@ -1430,39 +1545,84 @@ class Orchestrator:
                 continue
             try:
                 log.debug("Executing SSH command for commit %s", csha)
-                # Build SSH command with our configured SSH options
-                ssh_cmd = ["ssh", "-n", "-p", str(gerrit.port)]
-
-                # Add our SSH options if we have custom SSH config
-                if self._git_ssh_command:
-                    # Extract SSH options from GIT_SSH_COMMAND
-                    # Format: "ssh -i /path/to/key -o Option=value ..."
-                    git_ssh_parts = self._git_ssh_command.split()
-                    if len(git_ssh_parts) > 1:  # Skip the "ssh" part
-                        ssh_options = git_ssh_parts[1:]
-                        log.debug("Adding SSH options: %s", ssh_options)
-                        ssh_cmd.extend(ssh_options)
+                # Build SSH command. If isolated SSH key/known_hosts are
+                # available, use strict options; otherwise fall back to the
+                # minimal form expected by tests.
+                if self._ssh_key_path and self._ssh_known_hosts_path:
+                    ssh_cmd = [
+                        "ssh",
+                        "-F",
+                        "/dev/null",
+                        "-i",
+                        str(self._ssh_key_path),
+                        "-o",
+                        f"UserKnownHostsFile={self._ssh_known_hosts_path}",
+                        "-o",
+                        "IdentitiesOnly=yes",
+                        "-o",
+                        "IdentityAgent=none",
+                        "-o",
+                        "BatchMode=yes",
+                        "-o",
+                        "StrictHostKeyChecking=yes",
+                        "-o",
+                        "PasswordAuthentication=no",
+                        "-o",
+                        "PubkeyAcceptedKeyTypes=+ssh-rsa",
+                        "-n",
+                        "-p",
+                        str(gerrit.port),
+                        f"{user}@{server}",
+                        (
+                            "gerrit review -m "
+                            f"{shlex.quote(message)} "
+                            "--branch "
+                            f"{shlex.quote(branch)} "
+                            "--project "
+                            f"{shlex.quote(repo.project_gerrit)} "
+                            f"{shlex.quote(csha)}"
+                        ),
+                    ]
                 else:
-                    log.debug("No custom SSH config, using default SSH options")
-
-                # Add the target and gerrit command
-                ssh_cmd.extend(
-                    [
+                    # Strict non-interactive SSH without
+                    # isolated key/known_hosts
+                    ssh_cmd = [
+                        "ssh",
+                        "-F",
+                        "/dev/null",
+                        "-o",
+                        "IdentitiesOnly=yes",
+                        "-o",
+                        "IdentityAgent=none",
+                        "-o",
+                        "BatchMode=yes",
+                        "-o",
+                        "StrictHostKeyChecking=yes",
+                        "-o",
+                        "PasswordAuthentication=no",
+                        "-o",
+                        "PubkeyAcceptedKeyTypes=+ssh-rsa",
+                        "-n",
+                        "-p",
+                        str(gerrit.port),
                         f"{user}@{server}",
-                        "gerrit",
-                        "review",
-                        "-m",
-                        message,
-                        "--branch",
-                        branch,
-                        "--project",
-                        repo.project_gerrit,
-                        csha,
+                        (
+                            "gerrit review -m "
+                            f"{shlex.quote(message)} "
+                            "--branch "
+                            f"{shlex.quote(branch)} "
+                            "--project "
+                            f"{shlex.quote(repo.project_gerrit)} "
+                            f"{shlex.quote(csha)}"
+                        ),
                     ]
-                )
 
                 log.debug("Final SSH command: %s", " ".join(ssh_cmd))
-                run_cmd(ssh_cmd, cwd=self.workspace)
+                run_cmd(
+                    ssh_cmd,
+                    cwd=self.workspace,
+                    env=self._ssh_env(),
+                )
                 log.info(
                     "Successfully added back-reference comment for %s: %s",
                     csha,
@@ -1470,8 +1630,7 @@ class Orchestrator:
                 )
             except CommandError as exc:
                 log.warning(
-                    "Failed to add back-reference comment for %s "
-                    "(non-fatal): %s",
+                    "Failed to add back-reference comment for %s (non-fatal): %s",
                     csha,
                     exc,
                 )
@@ -1487,14 +1646,11 @@ class Orchestrator:
                 # Continue processing - this is not a fatal error
             except Exception as exc:
                 log.warning(
-                    "Failed to add back-reference comment for %s "
-                    "(non-fatal): %s",
+                    "Failed to add back-reference comment for %s (non-fatal): %s",
                     csha,
                     exc,
                 )
-                log.debug(
-                    "Back-reference comment failure details:", exc_info=True
-                )
+                log.debug("Back-reference comment failure details:", exc_info=True)
                 # Continue processing - this is not a fatal error
 
     def _comment_on_pull_request(
@@ -1509,10 +1665,10 @@ class Orchestrator:
             return
         urls = result.change_urls or []
         org = os.getenv("ORGANIZATION", gh.repository_owner)
-        text = (
-            f"The pull-request PR-{gh.pr_number} is submitted to Gerrit "
-            f"[{org}](https://{gerrit.host})!\n\n"
-        )
+        # Create centralized URL builder for organization link
+        url_builder = create_gerrit_url_builder(gerrit.host)
+        org_url = url_builder.web_url()
+        text = f"The pull-request PR-{gh.pr_number} is submitted to Gerrit [{org}]({org_url})!\n\n"
         if urls:
             text += "To follow up on the change visit:\n\n" + "\n".join(urls)
         try:
@@ -1521,6 +1677,13 @@ class Orchestrator:
             # At this point, gh.pr_number is non-None due to earlier guard.
             pr_obj = get_pull(repo, int(gh.pr_number))
             create_pr_comment(pr_obj, text)
+            # Also post a succinct one-line comment
+            # for each Gerrit change URL
+            for u in urls:
+                create_pr_comment(
+                    pr_obj,
+                    f"Change raised in Gerrit by GitHub2Gerrit: {u}",
+                )
         except Exception as exc:
             log.warning("Failed to add PR comment: %s", exc)
 
@@ -1582,20 +1745,15 @@ class Orchestrator:
             "yes",
             "on",
         ):
+            log.info("Dry-run: network checks disabled (G2G_DRYRUN_DISABLE_NETWORK)")
             log.info(
-                "Dry-run: network checks disabled (G2G_DRYRUN_DISABLE_NETWORK)"
-            )
-            log.info(
-                "Dry-run targets: Gerrit project=%s branch=%s "
-                "topic_prefix=GH-%s",
+                "Dry-run targets: Gerrit project=%s branch=%s topic_prefix=GH-%s",
                 repo.project_gerrit,
                 self._resolve_target_branch(),
                 repo.project_github,
             )
             if inputs.reviewers_email:
-                log.info(
-                    "Reviewers (from inputs/config): %s", inputs.reviewers_email
-                )
+                log.info("Reviewers (from inputs/config): %s", inputs.reviewers_email)
             elif os.getenv("REVIEWERS_EMAIL"):
                 log.info(
                     "Reviewers (from environment): %s",
@@ -1606,18 +1764,14 @@ class Orchestrator:
         # DNS resolution for Gerrit host
         try:
             socket.getaddrinfo(gerrit.host, None)
-            log.info(
-                "DNS resolution for Gerrit host '%s' succeeded", gerrit.host
-            )
+            log.info("DNS resolution for Gerrit host '%s' succeeded", gerrit.host)
         except Exception as exc:
             msg = "DNS resolution failed"
             raise OrchestratorError(msg) from exc
 
         # SSH (TCP) reachability on Gerrit port
         try:
-            with socket.create_connection(
-                (gerrit.host, gerrit.port), timeout=5
-            ):
+            with socket.create_connection((gerrit.host, gerrit.port), timeout=5):
                 pass
             log.info(
                 "SSH TCP connectivity to %s:%s verified",
@@ -1630,10 +1784,7 @@ class Orchestrator:
 
         # Gerrit REST reachability and optional auth check
         base_path = os.getenv("GERRIT_HTTP_BASE_PATH", "").strip().strip("/")
-        http_user = (
-            os.getenv("GERRIT_HTTP_USER", "").strip()
-            or os.getenv("GERRIT_SSH_USER_G2G", "").strip()
-        )
+        http_user = os.getenv("GERRIT_HTTP_USER", "").strip() or os.getenv("GERRIT_SSH_USER_G2G", "").strip()
         http_pass = os.getenv("GERRIT_HTTP_PASSWORD", "").strip()
         self._verify_gerrit_rest(gerrit.host, base_path, http_user, http_pass)
 
@@ -1643,9 +1794,7 @@ class Orchestrator:
             repo_obj = get_repo_from_env(client)
             if gh.pr_number is not None:
                 pr_obj = get_pull(repo_obj, gh.pr_number)
-                log.info(
-                    "GitHub PR #%s metadata loaded successfully", gh.pr_number
-                )
+                log.info("GitHub PR #%s metadata loaded successfully", gh.pr_number)
                 try:
                     title, _ = get_pr_title_body(pr_obj)
                     log.info("GitHub PR title: %s", title)
@@ -1671,13 +1820,9 @@ class Orchestrator:
             repo.project_github,
         )
         if inputs.reviewers_email:
-            log.info(
-                "Reviewers (from inputs/config): %s", inputs.reviewers_email
-            )
+            log.info("Reviewers (from inputs/config): %s", inputs.reviewers_email)
         elif os.getenv("REVIEWERS_EMAIL"):
-            log.info(
-                "Reviewers (from environment): %s", os.getenv("REVIEWERS_EMAIL")
-            )
+            log.info("Reviewers (from environment): %s", os.getenv("REVIEWERS_EMAIL"))
 
     def _verify_gerrit_rest(
         self,
@@ -1691,15 +1836,13 @@ class Orchestrator:
         def _build_client(url: str) -> Any:
             if http_user and http_pass:
                 if GerritRestAPI is None:
-                    raise OrchestratorError("pygerrit2 missing")  # noqa: TRY003
+                    raise OrchestratorError(_MSG_PYGERRIT2_MISSING)
                 if HTTPBasicAuth is None:
-                    raise OrchestratorError("pygerrit2 auth missing")  # noqa: TRY003
-                return GerritRestAPI(
-                    url=url, auth=HTTPBasicAuth(http_user, http_pass)
-                )
+                    raise OrchestratorError(_MSG_PYGERRIT2_AUTH_MISSING)
+                return GerritRestAPI(url=url, auth=HTTPBasicAuth(http_user, http_pass))
             else:
                 if GerritRestAPI is None:
-                    raise OrchestratorError("pygerrit2 missing")  # noqa: TRY003
+                    raise OrchestratorError(_MSG_PYGERRIT2_MISSING)
                 return GerritRestAPI(url=url)
 
         def _probe(url: str) -> None:
@@ -1714,29 +1857,30 @@ class Orchestrator:
                 _ = rest.get("/dashboard/self")
                 log.info("Gerrit REST endpoint reachable (unauthenticated)")
 
-        base_url = (
-            f"https://{host}/"
-            if not base_path
-            else f"https://{host}/{base_path}/"
-        )
-        try:
-            _probe(base_url)
-        except Exception as exc:
-            status = getattr(
-                getattr(exc, "response", None), "status_code", None
+        # Create centralized URL builder for REST probing
+        url_builder = create_gerrit_url_builder(host, base_path)
+        api_candidates = url_builder.get_api_url_candidates()
+
+        # Try API URLs in order of preference
+        probe_successful = False
+        last_error = None
+
+        for api_url in api_candidates:
+            try:
+                _probe(api_url)
+                probe_successful = True
+                break
+            except Exception as exc:
+                last_error = exc
+                log.debug("Gerrit REST probe failed for %s: %s", api_url, exc)
+                continue
+
+        if not probe_successful and last_error:
+            log.warning(
+                "Gerrit REST probe did not succeed (tried %d URLs): %s",
+                len(api_candidates),
+                last_error,
             )
-            if not base_path and status == 404:
-                try:
-                    fallback_url = f"https://{host}/r/"
-                    _probe(fallback_url)
-                except Exception as exc2:
-                    log.warning(
-                        "Gerrit REST probe did not succeed "
-                        "(including '/r' fallback): %s",
-                        exc2,
-                    )
-            else:
-                log.warning("Gerrit REST probe did not succeed: %s", exc)
 
     # ---------------
     # Helpers