github2gerrit 2.2.0__tar.gz → 2.2.2__tar.gz

{github2gerrit-2.2.0 → github2gerrit-2.2.2}/.pre-commit-config.yaml

@@ -64,7 +64,7 @@ repos:
         types: [yaml]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: e8f7d69b957a30acb2c875078d5fd012de24b64c  # frozen: v0.16.7
+    rev: 2eeb5678de71a00c0902cbda7105d328432f72cb  # frozen: v0.16.8
     hooks:
       - id: ruff
         files: ^(src|scripts|tests)/.+\.py$|^sitecustomize\.py$
@@ -72,6 +72,24 @@ repos:
       - id: ruff-format
         files: ^(src|scripts|tests)/.+\.py$|^sitecustomize\.py$
 
+  - repo: local
+    hooks:
+      - id: sync-mypy-pins
+        # Rewrites the mypy hook's exact pins below to the versions
+        # uv.lock records, so the two cannot drift. Ordered ahead of the
+        # mypy hook so the pins are corrected before mypy is reached,
+        # though pre-commit reads this file and builds hook environments
+        # before any hook runs: a rewrite fails this run, as any
+        # modifying hook does, and the corrected pins take effect on the
+        # rerun. Both files come from the same checkout, so the verdict
+        # is the same locally and in CI, and a Dependabot lockfile bump
+        # fails here on its own pull request rather than on main.
+        name: sync mypy hook pins with uv.lock
+        entry: python3 scripts/sync_mypy_pins.py
+        language: system
+        files: ^(\.pre-commit-config\.yaml|uv\.lock)$
+        pass_filenames: false
+
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: 7ff8d35ae36a7d2b968f2f90b4c723e292e594ee  # frozen: v2.3.1
     hooks:
@@ -100,10 +118,16 @@ repos:
         # nobody runs locally. That drift is not theoretical: CI once
         # resolved typer 0.27.2 against a lockfile holding 0.27.1, and the
         # two disagreed about which module typer.Exit lives in.
-        # Every version here must equal the one uv.lock records for that
-        # package, so update both together (after `uv lock --upgrade`, for
-        # instance). tests/test_precommit_mypy_pins.py compares the two
-        # files and fails if they diverge in either direction.
+        # The versions are not maintained by hand: the sync-mypy-pins hook
+        # above rewrites them from uv.lock, so after `uv lock --upgrade` a
+        # `prek run sync-mypy-pins --all-files` brings them into step
+        # (--all-files, because neither file is staged at that point and
+        # the hook would otherwise not be selected). The tests in
+        # tests/test_precommit_mypy_pins.py check the list is exact and
+        # complete against the imports; they deliberately do not compare
+        # versions to the lockfile, since a pull request is tested as
+        # merged into main and would otherwise fail for a dependency that
+        # moved there, not for anything on the branch.
         #
         # These pins do not freeze the whole resolved closure: pip still
         # picks transitive versions at build time, and listing every
@@ -119,8 +143,9 @@ repos:
         # runs, and nothing otherwise ties it to the locked one, so an
         # autoupdate of the mirror or a lockfile-only mypy upgrade would
         # leave the hook running a different checker in silence. With the
-        # pin present, the test compares it against uv.lock, and a mirror
-        # whose rev disagrees fails to install rather than quietly winning.
+        # pin present, the sync hook keeps it at the locked version, and a
+        # mirror whose rev disagrees fails to install rather than quietly
+        # winning.
         additional_dependencies:
           - mypy==2.3.1
           - click==8.5.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: github2gerrit
-Version: 2.2.0
+Version: 2.2.2
 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_PORT`           | No       | `"29418"`        | Gerrit SSH port                                                |
-| `GERRIT_PROJECT`               | No       | `""`             | Gerrit project name; `.gitreview` preferred                    |
+| `GERRIT_SERVER`                | No       | `""`             | Gerrit server hostname; overrides `.gitreview` when set        |
+| `GERRIT_SERVER_PORT`           | No       | `""`             | Gerrit SSH port; `.gitreview`'s when unset, else 29418         |
+| `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
@@ -376,7 +377,7 @@ Input defaults match the composite action defaults.
 | `GERRIT_SSH_USER_G2G`          | string  | `""`             | Gerrit SSH username                              |
 | `GERRIT_SSH_USER_G2G_EMAIL`    | string  | `""`             | Gerrit user email address                        |
 | `GERRIT_SERVER`                | string  | `""`             | Gerrit server hostname                           |
-| `GERRIT_SERVER_PORT`           | string  | `"29418"`        | Gerrit SSH port                                  |
+| `GERRIT_SERVER_PORT`           | string  | `""`             | Gerrit SSH port; `.gitreview`'s when unset       |
 | `GERRIT_PROJECT`               | string  | `""`             | Gerrit project name                              |
 | `GERRIT_HTTP_BASE_PATH`        | string  | `""`             | HTTP base path for Gerrit REST                   |
 | `GERRIT_HTTP_USER`             | string  | `""`             | Gerrit HTTP user for REST queries                |

{github2gerrit-2.2.0 → github2gerrit-2.2.2}/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_PORT`           | No       | `"29418"`        | Gerrit SSH port                                                |
-| `GERRIT_PROJECT`               | No       | `""`             | Gerrit project name; `.gitreview` preferred                    |
+| `GERRIT_SERVER`                | No       | `""`             | Gerrit server hostname; overrides `.gitreview` when set        |
+| `GERRIT_SERVER_PORT`           | No       | `""`             | Gerrit SSH port; `.gitreview`'s when unset, else 29418         |
+| `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
@@ -329,7 +330,7 @@ Input defaults match the composite action defaults.
 | `GERRIT_SSH_USER_G2G`          | string  | `""`             | Gerrit SSH username                              |
 | `GERRIT_SSH_USER_G2G_EMAIL`    | string  | `""`             | Gerrit user email address                        |
 | `GERRIT_SERVER`                | string  | `""`             | Gerrit server hostname                           |
-| `GERRIT_SERVER_PORT`           | string  | `"29418"`        | Gerrit SSH port                                  |
+| `GERRIT_SERVER_PORT`           | string  | `""`             | Gerrit SSH port; `.gitreview`'s when unset       |
 | `GERRIT_PROJECT`               | string  | `""`             | Gerrit project name                              |
 | `GERRIT_HTTP_BASE_PATH`        | string  | `""`             | HTTP base path for Gerrit REST                   |
 | `GERRIT_HTTP_USER`             | string  | `""`             | Gerrit HTTP user for REST queries                |

{github2gerrit-2.2.0 → github2gerrit-2.2.2}/action.yaml

@@ -133,9 +133,9 @@ inputs:
     required: false
     default: ""
   GERRIT_SERVER_PORT:
-    description: "Gerrit server SSH TCP port"
+    description: "Gerrit server SSH TCP port; .gitreview's when unset, else 29418"
     required: false
-    default: "29418"
+    default: ""
   GERRIT_PROJECT:
     description: "Gerrit project; optional if .gitreview exists"
     required: false
@@ -266,7 +266,7 @@ runs:
     - name: "Setup uv"
       if: steps.disabled-check.outputs.disabled != 'true'
       # yamllint disable-line rule:line-length
-      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d  # v10.0.1
+      uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4  # v10.1.0
       with:
         enable-cache: false
 

{github2gerrit-2.2.0 → github2gerrit-2.2.2}/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-port INTEGER`       | `GERRIT_SERVER_PORT`        | `29418` | Gerrit SSH port                                              |
-| `--gerrit-project TEXT`              | `GERRIT_PROJECT`            | `""`    | Gerrit project (optional; `.gitreview` preferred)            |
+| `--gerrit-server TEXT`               | `GERRIT_SERVER`             | `""`    | Gerrit server hostname (optional; overrides `.gitreview`)    |
+| `--gerrit-server-port INTEGER`       | `GERRIT_SERVER_PORT`        | unset   | Gerrit SSH port; `.gitreview`'s when unset, else 29418       |
+| `--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.2}/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,23 @@ 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. The port input has no default: the action and the CLI pass none
+   when the caller gave none, so a set port is distinguishable from an
+   unset one. 29418 applies only when neither an input nor `.gitreview`
+   names a port.
+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 +429,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 +838,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 +1013,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`