github2gerrit 2.2.0__tar.gz → 2.2.1__tar.gz

{github2gerrit-2.2.0 → github2gerrit-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: github2gerrit
-Version: 2.2.0
+Version: 2.2.1
 Summary: Submit a GitHub pull request to a Gerrit repository.
 Project-URL: Homepage, https://github.com/lfreleng-actions/github2gerrit-action
 Project-URL: Repository, https://github.com/lfreleng-actions/github2gerrit-action
@@ -276,9 +276,9 @@ uvx github2gerrit https://github.com/onap/portal-ng-bff/pull/33
 | `GERRIT_KNOWN_HOSTS`           | No       | —                | Known hosts entries for Gerrit SSH (auto-populated when empty) |
 | `GERRIT_SSH_USER_G2G`          | No       | `""`             | Gerrit SSH username; derived when not supplied                 |
 | `GERRIT_SSH_USER_G2G_EMAIL`    | No       | `""`             | Gerrit user email address; derived when not supplied           |
-| `GERRIT_SERVER`                | No       | `""`             | Gerrit server hostname; `.gitreview` preferred                 |
+| `GERRIT_SERVER`                | No       | `""`             | Gerrit server hostname; overrides `.gitreview` when set        |
 | `GERRIT_SERVER_PORT`           | No       | `"29418"`        | Gerrit SSH port                                                |
-| `GERRIT_PROJECT`               | No       | `""`             | Gerrit project name; `.gitreview` preferred                    |
+| `GERRIT_PROJECT`               | No       | `""`             | Gerrit project name; overrides `.gitreview` when set           |
 | `GERRIT_HTTP_BASE_PATH`        | No       | `""`             | HTTP base path for Gerrit REST API (e.g. `/r`)                 |
 | `GERRIT_HTTP_USER`             | No       | `""`             | Gerrit HTTP user for REST queries                              |
 | `GERRIT_HTTP_PASSWORD`         | No       | `""`             | Gerrit HTTP password/token for REST queries                    |
@@ -326,14 +326,15 @@ environment variables do not cross the `workflow_call` boundary. See
 [docs/cli.md](docs/cli.md) for the full option reference and
 [docs/features.md](docs/features.md) for feature-specific settings.
 
-Nine `G2G_`-prefixed settings can come from repository or organisation
+Ten `G2G_`-prefixed settings can come from repository or organisation
 **variables**, which the reusable workflow reads and passes to the
-action — among them `G2G_TRUSTED_ASSOCIATIONS`, `G2G_TOPIC_PREFIX`
-and `G2G_ENABLE_DERIVATION`, plus the `G2G_NO_GERRIT` and
-`G2G_DISABLED` kill switches. An organisation can set one once for
-every repository beneath it. A workflow calling the composite action
-directly does not inherit those variables; map them in with `env:`
-yourself. See [docs/cli.md](docs/cli.md) for the full list.
+action — among them `G2G_TRUSTED_ASSOCIATIONS`, `G2G_TOPIC_PREFIX`,
+`G2G_ENABLE_DERIVATION` and the `G2G_RESOLVE_PROJECT_VIA_GERRIT`
+opt-in, plus the `G2G_NO_GERRIT` and `G2G_DISABLED` kill switches. An
+organisation can set one once for every repository beneath it. A
+workflow calling the composite action directly does not inherit those
+variables; map them in with `env:` yourself. See
+[docs/cli.md](docs/cli.md) for the full list.
 
 The three `G2G_APPROVER*` inputs widen who may clear the fork approval
 gate, and each defaults to off. `G2G_INFO_YAML_MATCH_LFID` carries a

{github2gerrit-2.2.0 → github2gerrit-2.2.1}/README.md

@@ -229,9 +229,9 @@ uvx github2gerrit https://github.com/onap/portal-ng-bff/pull/33
 | `GERRIT_KNOWN_HOSTS`           | No       | —                | Known hosts entries for Gerrit SSH (auto-populated when empty) |
 | `GERRIT_SSH_USER_G2G`          | No       | `""`             | Gerrit SSH username; derived when not supplied                 |
 | `GERRIT_SSH_USER_G2G_EMAIL`    | No       | `""`             | Gerrit user email address; derived when not supplied           |
-| `GERRIT_SERVER`                | No       | `""`             | Gerrit server hostname; `.gitreview` preferred                 |
+| `GERRIT_SERVER`                | No       | `""`             | Gerrit server hostname; overrides `.gitreview` when set        |
 | `GERRIT_SERVER_PORT`           | No       | `"29418"`        | Gerrit SSH port                                                |
-| `GERRIT_PROJECT`               | No       | `""`             | Gerrit project name; `.gitreview` preferred                    |
+| `GERRIT_PROJECT`               | No       | `""`             | Gerrit project name; overrides `.gitreview` when set           |
 | `GERRIT_HTTP_BASE_PATH`        | No       | `""`             | HTTP base path for Gerrit REST API (e.g. `/r`)                 |
 | `GERRIT_HTTP_USER`             | No       | `""`             | Gerrit HTTP user for REST queries                              |
 | `GERRIT_HTTP_PASSWORD`         | No       | `""`             | Gerrit HTTP password/token for REST queries                    |
@@ -279,14 +279,15 @@ environment variables do not cross the `workflow_call` boundary. See
 [docs/cli.md](docs/cli.md) for the full option reference and
 [docs/features.md](docs/features.md) for feature-specific settings.
 
-Nine `G2G_`-prefixed settings can come from repository or organisation
+Ten `G2G_`-prefixed settings can come from repository or organisation
 **variables**, which the reusable workflow reads and passes to the
-action — among them `G2G_TRUSTED_ASSOCIATIONS`, `G2G_TOPIC_PREFIX`
-and `G2G_ENABLE_DERIVATION`, plus the `G2G_NO_GERRIT` and
-`G2G_DISABLED` kill switches. An organisation can set one once for
-every repository beneath it. A workflow calling the composite action
-directly does not inherit those variables; map them in with `env:`
-yourself. See [docs/cli.md](docs/cli.md) for the full list.
+action — among them `G2G_TRUSTED_ASSOCIATIONS`, `G2G_TOPIC_PREFIX`,
+`G2G_ENABLE_DERIVATION` and the `G2G_RESOLVE_PROJECT_VIA_GERRIT`
+opt-in, plus the `G2G_NO_GERRIT` and `G2G_DISABLED` kill switches. An
+organisation can set one once for every repository beneath it. A
+workflow calling the composite action directly does not inherit those
+variables; map them in with `env:` yourself. See
+[docs/cli.md](docs/cli.md) for the full list.
 
 The three `G2G_APPROVER*` inputs widen who may clear the fork approval
 gate, and each defaults to off. `G2G_INFO_YAML_MATCH_LFID` carries a

{github2gerrit-2.2.0 → github2gerrit-2.2.1}/docs/cli.md

@@ -100,9 +100,9 @@ set by GitHub Actions) and undergo proper boolean parsing.
 
 | Flag(s)                              | Env var                     | Default | Description                                                  |
 | ------------------------------------ | --------------------------- | ------- | ------------------------------------------------------------ |
-| `--gerrit-server TEXT`               | `GERRIT_SERVER`             | `""`    | Gerrit server hostname (optional; `.gitreview` preferred)    |
+| `--gerrit-server TEXT`               | `GERRIT_SERVER`             | `""`    | Gerrit server hostname (optional; overrides `.gitreview`)    |
 | `--gerrit-server-port INTEGER`       | `GERRIT_SERVER_PORT`        | `29418` | Gerrit SSH port                                              |
-| `--gerrit-project TEXT`              | `GERRIT_PROJECT`            | `""`    | Gerrit project (optional; `.gitreview` preferred)            |
+| `--gerrit-project TEXT`              | `GERRIT_PROJECT`            | `""`    | Gerrit project (optional; overrides `.gitreview` when set)   |
 | `--gerrit-ssh-user-g2g TEXT`         | `GERRIT_SSH_USER_G2G`       | `""`    | Gerrit SSH username (e.g., automation bot account)           |
 | `--gerrit-ssh-user-g2g-email TEXT`   | `GERRIT_SSH_USER_G2G_EMAIL` | `""`    | Email address for the Gerrit SSH user                        |
 | `--gerrit-ssh-privkey-g2g TEXT`      | `GERRIT_SSH_PRIVKEY_G2G`    | `""`    | SSH private key content used to authenticate to Gerrit       |
@@ -160,11 +160,12 @@ Some settings have no CLI flag and use environment variables.
 When running the tool as a GitHub Action, how you set one depends on the
 integration:
 
-- **Reusable workflow** — the workflow reads these nine names from repository
+- **Reusable workflow** — the workflow reads these ten names from repository
   or organisation **variables**:
   `G2G_TRUSTED_ASSOCIATIONS`, `G2G_TOPIC_PREFIX`, `G2G_SKIP_GERRIT_COMMENTS`,
   `G2G_ENABLE_DERIVATION`, `G2G_ANON_SUPERSEDE_FALLBACK`, `G2G_SHOW_PROGRESS`,
-  `G2G_LOG_LEVEL`, `G2G_NO_GERRIT` and `G2G_DISABLED`.
+  `G2G_LOG_LEVEL`, `G2G_RESOLVE_PROJECT_VIA_GERRIT`, `G2G_NO_GERRIT` and
+  `G2G_DISABLED`.
 
   The last two predate the rest and behave differently: `G2G_NO_GERRIT` is
   also a workflow input, taking the input first and falling back to the
@@ -187,34 +188,35 @@ forwarded setting treats blank as unset and keeps its documented default.
 
 <!-- markdownlint-disable MD013 -->
 
-| Variable                      | Default                                     | Description                                                                      |
-| ----------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------- |
-| `G2G_CONFIG_PATH`             | `~/.config/github2gerrit/configuration.txt` | Path to the per-organization configuration file                                  |
-| `G2G_LOG_LEVEL`               | `WARNING`                                   | Logging level; set `DEBUG` for verbose output                                    |
-| `G2G_TOPIC_PREFIX`            | `GH`                                        | Prefix used when generating Gerrit topics                                        |
-| `G2G_SKIP_GERRIT_COMMENTS`    | `false`                                     | Skip posting back-reference comments on Gerrit changes                           |
-| `G2G_TRUSTED_ASSOCIATIONS`    | `OWNER,MEMBER,COLLABORATOR`                 | Author associations trusted to issue `@github2gerrit` comment directives         |
-| `G2G_ENABLE_DERIVATION`       | `true`                                      | Enable automatic derivation of Gerrit parameters from organization defaults      |
-| `G2G_AUTO_SAVE_CONFIG`        | context-dependent                           | Save derived parameters back to the configuration file                           |
-| `G2G_RESPECT_USER_SSH`        | `false` (`true` in direct URL mode)         | Use the local user's SSH configuration and keys instead of provided key material |
-| `G2G_USE_SSH_AGENT`           | `true`                                      | Use SSH agent authentication; set `false` to force file-based SSH keys           |
-| `G2G_NO_GERRIT`               | `false`                                     | Run the full pipeline without contacting Gerrit (forces dry-run behavior)        |
-| `G2G_DISABLED`                | `false`                                     | Exit immediately with success without processing anything                        |
-| `CLEANUP_ABANDONED`           | `true`                                      | Close GitHub PRs whose Gerrit changes have status abandoned                      |
-| `CLEANUP_GERRIT`              | `true`                                      | Abandon Gerrit changes for closed GitHub PRs                                     |
-| `PR_NUMBER`                   | unset                                       | Pull request number to process in CI/CD mode (`0` means bulk mode)               |
-| `SYNC_ALL_OPEN_PRS`           | `false`                                     | Process all open PRs in the repository (bulk mode)                               |
-| `GERRIT_HTTP_USER`            | unset                                       | Username for the Gerrit REST API (when required)                                 |
-| `GERRIT_HTTP_PASSWORD`        | unset                                       | HTTP password/token for the Gerrit REST API                                      |
-| `GERRIT_HTTP_BASE_PATH`       | unset                                       | Gerrit REST base path for non-standard deployments (e.g., `/r`)                  |
-| `GITHUB_TOKEN`                | unset                                       | GitHub API token; required for PR queries, comments, and closing PRs             |
-| `GH_TOKEN`                    | unset                                       | Fallback source for `GITHUB_TOKEN` when the latter is unset                      |
-| `GERRIT_CHANGE_URL`           | unset                                       | Gerrit change URL for Gerrit-event dispatch mode (close the source PR)           |
-| `GERRIT_EVENT_TYPE`           | unset                                       | Gerrit event type for dispatch mode (`change-merged` or `change-abandoned`)      |
-| `GERRIT_BRANCH`               | unset                                       | Gerrit branch for dispatch mode change queries                                   |
-| `G2G_DRYRUN_DISABLE_NETWORK`  | `false`                                     | Skip DNS/network checks in dry-run; set automatically by `G2G_NO_GERRIT`         |
-| `G2G_ANON_SUPERSEDE_FALLBACK` | `true`                                      | Allow anonymous supersession queries when Gerrit credentials are unavailable     |
-| `VERIFY_DIGEST_STRICT`        | `true`                                      | Fail (rather than warn) on reconciliation digest mismatch after push             |
+| Variable                         | Default                                     | Description                                                                       |
+| -------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------- |
+| `G2G_CONFIG_PATH`                | `~/.config/github2gerrit/configuration.txt` | Path to the per-organization configuration file                                   |
+| `G2G_LOG_LEVEL`                  | `WARNING`                                   | Logging level; set `DEBUG` for verbose output                                     |
+| `G2G_TOPIC_PREFIX`               | `GH`                                        | Prefix used when generating Gerrit topics                                         |
+| `G2G_RESOLVE_PROJECT_VIA_GERRIT` | `false`                                     | Without a `.gitreview`, ask Gerrit which project a hyphenated GitHub name maps to |
+| `G2G_SKIP_GERRIT_COMMENTS`       | `false`                                     | Skip posting back-reference comments on Gerrit changes                            |
+| `G2G_TRUSTED_ASSOCIATIONS`       | `OWNER,MEMBER,COLLABORATOR`                 | Author associations trusted to issue `@github2gerrit` comment directives          |
+| `G2G_ENABLE_DERIVATION`          | `true`                                      | Enable automatic derivation of Gerrit parameters from organization defaults       |
+| `G2G_AUTO_SAVE_CONFIG`           | context-dependent                           | Save derived parameters back to the configuration file                            |
+| `G2G_RESPECT_USER_SSH`           | `false` (`true` in direct URL mode)         | Use the local user's SSH configuration and keys instead of provided key material  |
+| `G2G_USE_SSH_AGENT`              | `true`                                      | Use SSH agent authentication; set `false` to force file-based SSH keys            |
+| `G2G_NO_GERRIT`                  | `false`                                     | Run the full pipeline without contacting Gerrit (forces dry-run behavior)         |
+| `G2G_DISABLED`                   | `false`                                     | Exit immediately with success without processing anything                         |
+| `CLEANUP_ABANDONED`              | `true`                                      | Close GitHub PRs whose Gerrit changes have status abandoned                       |
+| `CLEANUP_GERRIT`                 | `true`                                      | Abandon Gerrit changes for closed GitHub PRs                                      |
+| `PR_NUMBER`                      | unset                                       | Pull request number to process in CI/CD mode (`0` means bulk mode)                |
+| `SYNC_ALL_OPEN_PRS`              | `false`                                     | Process all open PRs in the repository (bulk mode)                                |
+| `GERRIT_HTTP_USER`               | unset                                       | Username for the Gerrit REST API (when required)                                  |
+| `GERRIT_HTTP_PASSWORD`           | unset                                       | HTTP password/token for the Gerrit REST API                                       |
+| `GERRIT_HTTP_BASE_PATH`          | unset                                       | Gerrit REST base path for non-standard deployments (e.g., `/r`)                   |
+| `GITHUB_TOKEN`                   | unset                                       | GitHub API token; required for PR queries, comments, and closing PRs              |
+| `GH_TOKEN`                       | unset                                       | Fallback source for `GITHUB_TOKEN` when the latter is unset                       |
+| `GERRIT_CHANGE_URL`              | unset                                       | Gerrit change URL for Gerrit-event dispatch mode (close the source PR)            |
+| `GERRIT_EVENT_TYPE`              | unset                                       | Gerrit event type for dispatch mode (`change-merged` or `change-abandoned`)       |
+| `GERRIT_BRANCH`                  | unset                                       | Gerrit branch for dispatch mode change queries                                    |
+| `G2G_DRYRUN_DISABLE_NETWORK`     | `false`                                     | Skip DNS/network checks in dry-run; set automatically by `G2G_NO_GERRIT`          |
+| `G2G_ANON_SUPERSEDE_FALLBACK`    | `true`                                      | Allow anonymous supersession queries when Gerrit credentials are unavailable      |
+| `VERIFY_DIGEST_STRICT`           | `true`                                      | Fail (rather than warn) on reconciliation digest mismatch after push              |
 
 <!-- markdownlint-enable MD013 -->
 

{github2gerrit-2.2.0 → github2gerrit-2.2.1}/docs/features.md

@@ -20,6 +20,7 @@ action in detail. For a quick start and the full inputs table, see the
 - [Duplicate Detection](#duplicate-detection)
 - [Commit Message Normalization](#commit-message-normalization)
 - [Change-ID Reconciliation](#change-id-reconciliation)
+- [Repository and Project Names](#repository-and-project-names)
 - [Configuration](#configuration)
 - [Behavior Details](#behavior-details)
 
@@ -402,16 +403,19 @@ signal never earns a fork unwarranted trust.
 
 Resolution order for a fork pull request:
 
-1. `.gitreview` from the base repository at the pull request's base branch,
+1. Explicit `GERRIT_SERVER` / `GERRIT_SERVER_PORT` / `GERRIT_PROJECT` inputs,
+   each for its own field — an operator configured them for this run
+2. `.gitreview` from the base repository at the pull request's base branch,
    via the GitHub API or `raw.githubusercontent.com`
-2. Explicit `GERRIT_SERVER` / `GERRIT_SERVER_PORT` / `GERRIT_PROJECT` inputs
 3. Per-organization configuration file
 4. Derivation from the organization name (`gerrit.[org].org`)
 
-The lookup stops at the base branch. It does not fall back to the repository
-default branch, and it does not read `.gitreview` through the API without an
-authoritative base ref, because either would answer for a branch the pull
-request does not target — and `.gitreview` outranks the explicit inputs.
+A value the tool's own derivation exported through those same variables does
+not count as explicit; the tool tracks which is which. The lookup stops at the
+base branch. It does not fall back to the repository default branch, and it
+does not read `.gitreview` through the API without an authoritative base ref,
+because either would answer for a branch the pull request does not target —
+and `.gitreview` outranks everything but an explicit input.
 
 The base repository's copy carries the same authority and lies outside an
 attacker's reach, so this costs no accuracy. Skipping straight to derivation
@@ -421,7 +425,9 @@ repositories whose name contains a hyphen that does not mark a path separator.
 For the same reason, the tool drops branch names that originate in the fork
 (`GITHUB_HEAD_REF` and the pull request head ref) from base-repository
 lookups. Duplicate detection, which resolves `.gitreview` independently and
-earlier, applies the same rule.
+earlier, applies the same rule, and so does parameter derivation: for an
+untrusted pull request it declines the workspace copy of `.gitreview` and the
+`master`/`main` fallbacks alike, reading the base branch only.
 
 Same-repository pull requests keep their previous behaviour and still read
 `.gitreview` from the pull request tree.
@@ -828,6 +834,69 @@ github2gerrit \
   https://github.com/owner/repo/pull/123
 ```
 
+## Repository and Project Names
+
+Gerrit projects are paths, such as `multicloud/openstack`; GitHub repository
+names are flat, such as `multicloud-openstack`. Linux Foundation mirrors
+flatten a path by replacing every `/` with `-`. One module, `project_names`,
+handles that mapping for the whole tool, so every part of it agrees on what a
+name means.
+
+### One direction is exact, the other is not
+
+Gerrit to GitHub is deterministic. GitHub to Gerrit is **ambiguous**: a hyphen
+is both the flattened separator and an ordinary character inside a segment.
+On gerrit.onap.org, `aai-aai-common` is `aai/aai-common`, not
+`aai/aai/common`, and nothing in the name can tell you which.
+
+So the tool resolves the Gerrit project from the best source it has, in this
+order:
+
+1. An explicit `GERRIT_PROJECT` input — an operator said so. A value the
+   tool's own parameter derivation exported through the same variable does
+   not count; the tool tracks which is which.
+2. The repository's `.gitreview` — the repository says so. For a pull request
+   the tool reads this from the **base** repository at the base ref, never
+   from a fork; see [Gerrit target resolution](#gerrit-target-resolution).
+3. Gerrit's own project list, when you enable
+   `G2G_RESOLVE_PROJECT_VIA_GERRIT` — the server says so. The tool checks
+   every reading of the hyphens against `GET /projects/?p=<first segment>`;
+   exactly one match resolves it, and on two matches the tool refuses to
+   choose.
+4. A project from the per-organization configuration file, or one an earlier
+   derivation pass exported — somebody wrote it down, but nothing confirms
+   it for this repository.
+5. A guess that every hyphen is a separator, logged as a guess. A name with
+   no hyphens has only one reading and is not a guess.
+
+The tool resolves the project once per run and uses the result both for the
+Gerrit topic and for the push target, so the two cannot disagree. A real run
+refuses to push to a guess: with no `.gitreview`, no `GERRIT_PROJECT`, and a
+hyphenated name, it stops with an error naming the ambiguity and the three
+ways to settle it. This holds for direct URL invocations too, since a URL
+names the GitHub side and says nothing about the Gerrit project. Dry runs
+proceed on the guess, since they push nothing. Queries — the close handler,
+the sweeps — still use the guess, because a wrong query costs nothing.
+
+Every Linux Foundation repository carries a `.gitreview`, so in practice step
+2 answers. Step 3 is off by default because it adds a network call to name
+resolution; enable it for repositories that have no `.gitreview` and whose
+names contain hyphens inside segments. It applies wherever the tool resolves a
+project, including the closed-pull-request handler and the cleanup sweeps,
+reads the opt-in from the configuration file as well as the environment, asks
+each server once per prefix per run, and stays off under `G2G_NO_GERRIT`, which
+promises no Gerrit calls at all.
+
+### Why this matters for cleanup
+
+The close handler, the bulk sweep and duplicate detection all query Gerrit
+with `project:<name>`. A wrong name matches nothing and the tool reports
+"no change found" rather than an error — which is how 239 changes across 43
+ONAP projects stayed open after their pull requests closed (#441). The tool
+now resolves the project from `.gitreview` before any of those paths run,
+reports at INFO level when it finds no change, naming the project it asked
+about, and reports a failed lookup as a failure rather than as "no change".
+
 ## Configuration
 
 ### Configuration Precedence
@@ -940,7 +1009,12 @@ provided, the tool derives them from these sources, in priority order:
 
 Organization-based pattern, from the `ORGANIZATION` value:
 
-- Gerrit server: `gerrit.{organization}.org` (or from config file)
+- Gerrit server: the repository's `.gitreview` host when the file exists,
+  else the configuration file's `GERRIT_SERVER`, else
+  `gerrit.{organization}.org`. The derived host travels with the derived
+  project as one target, because the closed-pull-request handler queries
+  them together and the pipeline pushes to the `.gitreview` host whenever
+  the file exists.
 - SSH username: `{organization}.gh2gerrit`
 - Email: `releng+{organization}-gh2gerrit@linuxfoundation.org`
 

{github2gerrit-2.2.0 → github2gerrit-2.2.1}/src/github2gerrit/cli.py

@@ -120,6 +120,46 @@ def _exit_for_pr_state_error(pr_number: int, pr_state: str) -> None:
     exit_for_pr_state_error(pr_number, pr_state)
 
 
+def _stop_for_pr_state(
+    gh: GitHubContext, pr_state: str, progress_tracker: Any = None
+) -> NoReturn:
+    """Stop because the pull request is not open.
+
+    On a pull request event this is not an error. GitHub delivers
+    several events around a close — Dependabot edits the body before
+    closing, for instance — and any of them may land after the
+    ``closed`` event whose handler already ran. Such a run has nothing
+    to do, and a red check on the contributor's pull request would
+    misreport that. The report behind #441 cited exactly this run and
+    took it for the close handler failing.
+
+    A dispatch or direct invocation naming a closed pull request is
+    different: somebody asked for that one specifically, and being told
+    it cannot be processed is the useful answer.
+    """
+    if gh.event_name in ("pull_request", "pull_request_target"):
+        log.info(
+            "Pull request #%s is %s; nothing to do for a '%s' event. Cleanup "
+            "for a closed pull request runs on the 'closed' event itself.",
+            gh.pr_number,
+            pr_state,
+            gh.event_action or gh.event_name,
+        )
+        safe_console_print(
+            f"⏩ Pull request #{gh.pr_number} is {pr_state}; nothing to do",
+            style="yellow",
+            progress_tracker=progress_tracker,
+        )
+        # The caller's own stop() is downstream of this raise, and
+        # safe_console_print only suspends and resumes the display, so
+        # an in-process caller catching the exit would otherwise be
+        # left with an active Rich context.
+        if progress_tracker is not None:
+            progress_tracker.stop()
+        raise typer.Exit(int(ExitCode.SUCCESS))
+    exit_for_pr_state_error(gh.pr_number or 0, pr_state)
+
+
 def _exit_for_pr_not_found(pr_number: int, repository: str) -> None:
     """Exit with error message for PR not found."""
     exit_for_pr_not_found(pr_number, repository)
@@ -756,10 +796,10 @@ def _extract_and_display_pr_info(
         repo = get_repo_from_env(client)
         pr_obj = get_pull(repo, int(gh.pr_number))
 
-        # Check PR state and exit if not processable
+        # Check PR state and stop if not processable
         pr_state = getattr(pr_obj, "state", "unknown")
         if pr_state != "open":
-            _exit_for_pr_state_error(gh.pr_number, pr_state)
+            _stop_for_pr_state(gh, str(pr_state), progress_tracker)
 
         # Check if automation_only is enabled and reject non-automation PRs
         _check_automation_only(pr_obj, gh, progress_tracker)
@@ -792,6 +832,12 @@ def _extract_and_display_pr_info(
     except GitHub2GerritError:
         # Let our structured errors propagate
         raise
+    except typer.Exit:
+        # display_and_exit and the clean stop above both raise this.
+        # It derives from Exception through click, so without this
+        # clause the handler below would swallow a deliberate exit 8
+        # and report "Failed to fetch PR details: 8" with exit 1.
+        raise
     except Exception as exc:
         log.debug("Failed to display PR info: %s", exc)
         if "404" in str(exc) or "Not Found" in str(exc):
@@ -1468,13 +1514,13 @@ def main(
         "",
         "--gerrit-project",
         envvar="GERRIT_PROJECT",
-        help="Gerrit project (optional; .gitreview preferred).",
+        help="Gerrit project (optional; overrides .gitreview when set).",
     ),
     gerrit_server: str = typer.Option(
         "",
         "--gerrit-server",
         envvar="GERRIT_SERVER",
-        help="Gerrit server hostname (optional; .gitreview preferred).",
+        help="Gerrit server hostname (optional; overrides .gitreview).",
     ),
     gerrit_server_port: int = typer.Option(
         29418,
@@ -3036,14 +3082,23 @@ def _log_abandoned_change_url(
 
 
 def _abandon_change_for_closed_pr(data: Inputs, gh: GitHubContext) -> None:
-    """Abandon the Gerrit change associated with a closed pull request."""
+    """Abandon the Gerrit change associated with a closed pull request.
+
+    Three outcomes, reported distinctly: a change was abandoned, no
+    open change carries this pull request's trailer, or the lookup or
+    abandon itself failed. The last two used to share one message, and
+    a failed query read as a clean "nothing to do". A failure does not
+    say which side of the abandon it happened on -- Gerrit may have
+    applied it and the response been lost -- so the report says the
+    state is unconfirmed rather than claiming the change is open.
+    """
     if gh.pr_number is None:
         return
+    log.debug(
+        "Checking for Gerrit change to abandon for PR #%s",
+        gh.pr_number,
+    )
     try:
-        log.debug(
-            "Checking for Gerrit change to abandon for PR #%s",
-            gh.pr_number,
-        )
         change_number = abandon_gerrit_change_for_closed_pr(
             pr_number=gh.pr_number,
             gerrit_server=data.gerrit_server,
@@ -3052,21 +3107,46 @@ def _abandon_change_for_closed_pr(data: Inputs, gh: GitHubContext) -> None:
             dry_run=data.dry_run,
             progress_tracker=None,
         )
-        if change_number:
-            _log_abandoned_change_url(data, gh, change_number)
-            # Console output already done by
-            # abandon_gerrit_change_for_closed_pr
-        else:
-            log.debug(
-                "No open Gerrit change found for pull request #%s",
-                gh.pr_number,
-            )
     except Exception as exc:
         log.warning(
-            "Failed to abandon Gerrit change for PR #%s: %s",
+            "Failed to look up or abandon the Gerrit change for pull "
+            "request #%s in project %r on %s: %s. Its state could not be "
+            "confirmed; check Gerrit.",
             gh.pr_number,
+            data.gerrit_project,
+            data.gerrit_server,
             exc,
         )
+        log.debug("Cleanup failure detail", exc_info=True)
+        safe_console_print(
+            f"⚠️  Could not confirm the Gerrit change state for PR "
+            f"#{gh.pr_number}: {exc}",
+            style="yellow",
+        )
+        return
+
+    if change_number:
+        _log_abandoned_change_url(data, gh, change_number)
+        # Console output already done by
+        # abandon_gerrit_change_for_closed_pr
+        return
+
+    # Audible on purpose. This is the outcome when the project name is
+    # wrong, and at debug level it hid 239 stranded changes on one
+    # server for six months (#441). Naming the project queried is what
+    # lets a reader spot the mismatch.
+    log.info(
+        "No open Gerrit change found for pull request #%s in "
+        "project %r on %s; nothing to abandon",
+        gh.pr_number,
+        data.gerrit_project,
+        data.gerrit_server,
+    )
+    safe_console_print(
+        f"⏩ No open Gerrit change for PR #{gh.pr_number} in "
+        f"project '{data.gerrit_project}'",
+        style="dim",
+    )
 
 
 def _handle_pr_closed(
@@ -3104,13 +3184,28 @@ def _handle_pr_closed(
 
     # First, abandon the specific Gerrit change for this closed PR
     # Skip in G2G_NO_GERRIT: no Gerrit server to query
-    if (
-        not no_gerrit
-        and gh.pr_number
+    if no_gerrit:
+        pass
+    elif not (
+        gh.pr_number
+        and gh.repository
         and data.gerrit_server
         and data.gerrit_project
-        and gh.repository
     ):
+        # Say so. Silently skipping here is indistinguishable from a
+        # successful cleanup that found nothing, and the change stays
+        # open with no trace of why.
+        log.warning(
+            "Cannot look for a Gerrit change to abandon for PR #%s: "
+            "repository=%r server=%r project=%r. Set GERRIT_SERVER and "
+            "GERRIT_PROJECT, or add a .gitreview so they can be derived; "
+            "the repository comes from GITHUB_REPOSITORY.",
+            gh.pr_number,
+            gh.repository,
+            data.gerrit_server,
+            data.gerrit_project,
+        )
+    else:
         _abandon_change_for_closed_pr(data, gh)
 
     _run_gerrit_cleanup_tasks(data, gh, no_gerrit=no_gerrit)