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

github2gerrit/core.py

@@ -38,14 +38,6 @@ 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 .github_api import build_client
 from .github_api import close_pr
 from .github_api import create_pr_comment
@@ -67,9 +59,52 @@ 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,10 +122,13 @@ 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)
 
-    # Use the cleaned issue ID for insertion
-    issue_line = cleaned_issue_id
+    # 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}"
 
     lines = message.splitlines()
     if not lines:
@@ -232,7 +270,7 @@ class Orchestrator:
             return SubmissionResult(
                 change_urls=[], change_numbers=[], commit_shas=[]
             )
-        self._setup_ssh(inputs)
+        self._setup_ssh(inputs, gerrit)
 
         if inputs.submit_single_commits:
             prep = self._prepare_single_commits(inputs, gh, gerrit)
@@ -278,7 +316,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:
@@ -443,7 +481,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("-", "/")
@@ -463,7 +501,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)
@@ -483,13 +521,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
@@ -503,8 +541,46 @@ 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")
@@ -526,7 +602,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")
@@ -1081,6 +1157,7 @@ class Orchestrator:
             repo.project_gerrit,
             branch,
         )
+        log.debug("Starting git review push operation...")
         if single_commits:
             tmp_branch = os.getenv("G2G_TMP_BRANCH", "tmp_branch")
             run_cmd(["git", "checkout", tmp_branch], cwd=self.workspace)
@@ -1113,9 +1190,19 @@ class Orchestrator:
                 if self._git_ssh_command
                 else None
             )
+            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:
-            msg = f"Failed to push changes to Gerrit with git-review: {exc}"
+            # Analyze the specific failure reason from git review output
+            error_details = self._analyze_gerrit_push_failure(exc)
+            _log_exception_conditionally(
+                log, "Gerrit push failed: %s", error_details
+            )
+            msg = (
+                f"Failed to push changes to Gerrit with git-review: "
+                f"{error_details}"
+            )
             raise OrchestratorError(msg) from exc
         # Cleanup temporary branch used during preparation
         tmp_branch = (os.getenv("G2G_TMP_BRANCH", "") or "").strip()
@@ -1132,6 +1219,108 @@ class Orchestrator:
                 cwd=self.workspace,
             )
 
+    def _analyze_gerrit_push_failure(self, exc: CommandError) -> str:
+        """Analyze git review failure and provide helpful error message."""
+        stdout = exc.stdout or ""
+        stderr = exc.stderr or ""
+        combined_output = f"{stdout}\n{stderr}"
+        combined_lower = combined_output.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
+        ):
+            # Extract specific rejection reason from output
+            lines = combined_output.split("\n")
+            for line in lines:
+                if "! [remote rejected]" in line:
+                    # Extract the reason in parentheses
+                    if "(" in line and ")" in line:
+                        reason = line[line.find("(") + 1 : line.find(")")]
+                        return f"Gerrit rejected the push: {reason}"
+                    return f"Gerrit rejected the push: {line.strip()}"
+            return "Gerrit rejected the push for an unknown reason"
+        else:
+            return f"Unknown error: {exc}"
+
     def _query_gerrit_for_results(
         self,
         *,
@@ -1154,14 +1343,10 @@ class Orchestrator:
         )
         http_pass = os.getenv("GERRIT_HTTP_PASSWORD", "").strip()
         if GerritRestAPI is None:
-            raise OrchestratorError(  # noqa: TRY003
-                "pygerrit2 is required to query Gerrit REST API"
-            )
+            raise OrchestratorError(_MSG_PYGERRIT2_REQUIRED_REST)
         if http_user and http_pass:
             if HTTPBasicAuth is None:
-                raise OrchestratorError(  # noqa: TRY003
-                    "pygerrit2 is required for HTTP authentication"
-                )
+                raise OrchestratorError(_MSG_PYGERRIT2_REQUIRED_AUTH)
             rest = GerritRestAPI(
                 url=base_url, auth=HTTPBasicAuth(http_user, http_pass)
             )
@@ -1352,6 +1537,19 @@ class Orchestrator:
         if not commit_shas:
             log.warning("No commit shas to comment on in Gerrit")
             return
+
+        # Check if back-reference comments are disabled
+        if os.getenv("G2G_SKIP_GERRIT_COMMENTS", "").lower() in (
+            "true",
+            "1",
+            "yes",
+        ):
+            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
@@ -1368,12 +1566,24 @@ class Orchestrator:
                 continue
             try:
                 log.debug("Executing SSH command for commit %s", csha)
-                run_cmd(
+                # 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)
+                else:
+                    log.debug("No custom SSH config, using default SSH options")
+
+                # Add the target and gerrit command
+                ssh_cmd.extend(
                     [
-                        "ssh",
-                        "-n",
-                        "-p",
-                        str(gerrit.port),
                         f"{user}@{server}",
                         "gerrit",
                         "review",
@@ -1386,14 +1596,40 @@ class Orchestrator:
                         csha,
                     ]
                 )
+
+                log.debug("Final SSH command: %s", " ".join(ssh_cmd))
+                run_cmd(ssh_cmd, cwd=self.workspace)
                 log.info(
                     "Successfully added back-reference comment for %s: %s",
                     csha,
                     message,
                 )
-            except Exception:
-                log.exception(
-                    "Failed to add back-reference comment for %s", csha
+            except CommandError as exc:
+                log.warning(
+                    "Failed to add back-reference comment for %s "
+                    "(non-fatal): %s",
+                    csha,
+                    exc,
+                )
+                if exc.stderr:
+                    log.debug("SSH stderr: %s", exc.stderr)
+                if exc.stdout:
+                    log.debug("SSH stdout: %s", exc.stdout)
+                log.info(
+                    "Back-reference comment failed but change was successfully "
+                    "submitted. You can set G2G_SKIP_GERRIT_COMMENTS=true to "
+                    "disable these comments."
+                )
+                # 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",
+                    csha,
+                    exc,
+                )
+                log.debug(
+                    "Back-reference comment failure details:", exc_info=True
                 )
                 # Continue processing - this is not a fatal error
 
@@ -1591,15 +1827,15 @@ 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
+                    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:

github2gerrit/duplicate_detection.py

@@ -1,5 +1,5 @@
-# SPDX-FileCopyrightText: 2024 Matthew Watkins
 # SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2025 The Linux Foundation
 
 """
 Duplicate change detection for github2gerrit.

github2gerrit/github_api.py

@@ -30,6 +30,12 @@ from typing import TypeVar
 from typing import cast
 
 
+# Error message constants to comply with TRY003
+_MSG_PYGITHUB_REQUIRED = "PyGithub required"
+_MSG_MISSING_GITHUB_TOKEN = "missing GITHUB_TOKEN"  # noqa: S105
+_MSG_BAD_GITHUB_REPOSITORY = "bad GITHUB_REPOSITORY"
+
+
 class GithubExceptionType(Exception):
     pass
 
@@ -65,7 +71,7 @@ else:
 
     class Github:  # type: ignore[no-redef]
         def __init__(self, *args: Any, **kwargs: Any) -> None:
-            raise RuntimeError("PyGithub required")  # noqa: TRY003
+            raise RuntimeError(_MSG_PYGITHUB_REQUIRED)
 
 
 class GhIssueComment(Protocol):
@@ -123,6 +129,8 @@ def _getenv_str(name: str) -> str:
 def _backoff_delay(attempt: int, base: float = 0.5, cap: float = 6.0) -> float:
     # Exponential backoff with jitter; cap prevents unbounded waits.
     delay: float = float(min(base * (2 ** max(0, attempt - 1)), cap))
+    # Using random.uniform for jitter is appropriate here - we only need
+    # pseudorandom distribution to avoid thundering herd, not crypto security
     jitter: float = float(random.uniform(0.0, delay / 2.0))  # noqa: S311
     return float(delay + jitter)
 
@@ -199,7 +207,7 @@ def build_client(token: str | None = None) -> GhClient:
     """
     tok = token or _getenv_str("GITHUB_TOKEN")
     if not tok:
-        raise ValueError("missing GITHUB_TOKEN")  # noqa: TRY003
+        raise ValueError(_MSG_MISSING_GITHUB_TOKEN)
     # per_page improves pagination; adjust as needed.
     base_url = _getenv_str("GITHUB_API_URL")
     if not base_url:
@@ -240,7 +248,7 @@ def get_repo_from_env(client: GhClient) -> GhRepository:
     """Return the repository object based on GITHUB_REPOSITORY."""
     full = _getenv_str("GITHUB_REPOSITORY")
     if not full or "/" not in full:
-        raise ValueError("bad GITHUB_REPOSITORY")  # noqa: TRY003
+        raise ValueError(_MSG_BAD_GITHUB_REPOSITORY)
     repo = client.get_repo(full)
     return repo
 

github2gerrit/gitutils.py

@@ -20,6 +20,22 @@ from collections.abc import Mapping
 from collections.abc import Sequence
 from dataclasses import dataclass
 from pathlib import Path
+from typing import Any
+
+
+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)
 
 
 __all__ = [
@@ -41,6 +57,9 @@ __all__ = [
     "run_cmd_with_retries",
 ]
 
+# Error message constants to comply with TRY003
+_MSG_COMMIT_NO_MESSAGE = "Either message or message_file must be provided"
+
 
 _LOGGER_NAME = "github2gerrit.git"
 log = logging.getLogger(_LOGGER_NAME)
@@ -187,7 +206,7 @@ def run_cmd(
         )
     except subprocess.TimeoutExpired as exc:
         msg = f"Command timed out: {cmd!r}"
-        log.exception(msg)
+        _log_exception_conditionally(log, msg)
         # TimeoutExpired carries 'output' and 'stderr' attributes,
         # which may be bytes depending on invocation context.
         out = getattr(exc, "output", None)
@@ -201,7 +220,7 @@ def run_cmd(
         ) from exc
     except OSError as exc:
         msg = f"Failed to execute command: {cmd!r} ({exc})"
-        log.exception(msg)
+        _log_exception_conditionally(log, msg)
         raise CommandError(msg, cmd=cmd) from exc
 
     result = CommandResult(
@@ -258,7 +277,6 @@ def run_cmd_with_retries(
 
     predicate = retry_on or _default_retry_on
     attempt = 0
-    # removed unused variable 'last_res'
 
     while True:
         attempt += 1
@@ -472,7 +490,7 @@ def git_commit_new(
 ) -> None:
     """Create a new commit using message or message_file."""
     if not message and not message_file:
-        raise ValueError("Either message or message_file must be provided")  # noqa: TRY003
+        raise ValueError(_MSG_COMMIT_NO_MESSAGE)
 
     args: list[str] = ["commit"]
     if signoff: