github2gerrit 1.0.7__tar.gz → 1.0.9__tar.gz

{github2gerrit-1.0.7 → github2gerrit-1.0.9}/.pre-commit-config.yaml

@@ -59,7 +59,7 @@ repos:
         types: [yaml]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 0839f92796ae388643a08a21640a029b322be5c2  # frozen: v0.15.2
+    rev: b969e2851312ca2b24bbec879ba4954341d1bd12  # frozen: v0.15.5
     hooks:
       - id: ruff
         files: ^(src|scripts|tests)/.+\.py$
@@ -96,7 +96,7 @@ repos:
       - id: shellcheck
 
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: 76b3d32d3f4b965e1d6425253c59407420ae2c43  # frozen: v0.47.0
+    rev: e72a3ca1632f0b11a07d171449fe447a7ff6795e  # frozen: v0.48.0
     hooks:
       - id: markdownlint
         args: ["--fix", "--config", ".markdownlint.yaml"]
@@ -116,12 +116,12 @@ repos:
 
   # Check for misspellings in documentation files
   - repo: https://github.com/codespell-project/codespell
-    rev: 63c8f8312b7559622c0d82815639671ae42132ac # frozen: v2.4.1
+    rev: 2ccb47ff45ad361a21071a7eedda4c37e6ae8c5a  # frozen: v2.4.2
     hooks:
       - id: codespell
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: ec368acd16deee9c560c105ab6d27db4ee19a5ec  # frozen: 0.36.2
+    rev: 8db279a37c552206d2df62269ff6f9d31125815a  # frozen: 0.37.0
     hooks:
       - id: check-github-actions
       - id: check-github-workflows

{github2gerrit-1.0.7 → github2gerrit-1.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github2gerrit
-Version: 1.0.7
+Version: 1.0.9
 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
@@ -39,7 +39,6 @@ Requires-Dist: pytest-mock>=3.15.1; extra == 'dev'
 Requires-Dist: pytest>=9.0.2; extra == 'dev'
 Requires-Dist: responses>=0.25.8; extra == 'dev'
 Requires-Dist: ruff>=0.6.3; extra == 'dev'
-Requires-Dist: types-click>=7.1.8; extra == 'dev'
 Requires-Dist: types-requests>=2.31.0; extra == 'dev'
 Requires-Dist: types-urllib3>=1.26.25.14; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -147,6 +146,117 @@ If UPDATE fails to find existing change:
    To create a new change, trigger the 'opened' workflow action.
 ```
 
+## PR Comment Commands
+
+GitHub2Gerrit supports an extensible set of directives issued through
+pull request comments. Add a comment containing `@github2gerrit`
+followed by a command phrase and the tool will act on it during
+the next workflow run.
+
+### Command Format
+
+<!-- markdownlint-disable MD013 -->
+
+```text
+@github2gerrit <command>
+```
+
+<!-- markdownlint-enable MD013 -->
+
+- Commands are **case-insensitive** — `@github2gerrit Create Missing Change`
+  works the same as `@github2gerrit create missing change`.
+- Only the **latest** occurrence of each command takes effect when the same
+  command appears in more than one comment.
+- The tool logs unrecognised directives at debug level and ignores them.
+
+### Available Commands
+
+<!-- markdownlint-disable MD013 MD060 -->
+
+| Command | Aliases | Description |
+| --- | --- | --- |
+| `create missing change` | `create-missing`, `create missing` | Create a Gerrit change when an UPDATE operation cannot find an existing one |
+
+<!-- markdownlint-enable MD013 MD060 -->
+
+### Create Missing Change
+
+When a PR `synchronize` event fires, GitHub2Gerrit treats it as an
+**UPDATE** operation and expects a Gerrit change to exist. If the
+original `opened` event failed (for example due to a bug or transient
+error), no Gerrit change exists and every following update fails with:
+
+```text
+❌ UPDATE FAILED: Cannot update non-existent Gerrit change
+```
+
+The **create missing change** command resolves this without manual
+intervention in Gerrit. Two mechanisms trigger it:
+
+#### 1. PR Comment Directive
+
+Add a comment on the stuck pull request:
+
+```text
+@github2gerrit create missing change
+```
+
+Then re-trigger the workflow (push a trivial change or re-run the
+workflow manually). GitHub2Gerrit detects the directive, switches
+from UPDATE to CREATE mode, and pushes a new Gerrit change.
+
+#### 2. CLI Flag
+
+Outside GitHub Actions you can pass the flag directly:
+
+```shell
+github2gerrit \
+  --create-missing \
+  https://github.com/MyOrg/my-repo/pull/42
+```
+
+Or set the environment variable:
+
+```shell
+export CREATE_MISSING=true
+github2gerrit https://github.com/MyOrg/my-repo/pull/42
+```
+
+#### What Happens During Fallback
+
+1. The tool attempts the normal UPDATE flow and finds no existing
+   Gerrit change.
+2. It checks for `--create-missing` **or** scans PR comments for the
+   `@github2gerrit create missing change` directive.
+3. If authorised, the operation mode switches from UPDATE to CREATE.
+4. The tool posts a notice on the PR:
+
+   ```text
+   🔄 GitHub2Gerrit: No existing Gerrit change found for this PR.
+   Creating a new Gerrit change (fallback from UPDATE operation).
+   ```
+
+5. The pipeline continues as a normal CREATE — preparing commits,
+   pushing to Gerrit, posting the change URL back on the PR.
+
+#### GitHub Actions Workflow Example
+
+<!-- markdownlint-disable MD013 -->
+
+```yaml
+- name: Submit PR to Gerrit
+  uses: lfreleng-actions/github2gerrit-action@main
+  with:
+    GERRIT_SSH_PRIVKEY_G2G: ${{ secrets.GERRIT_SSH_PRIVKEY_G2G }}
+    CREATE_MISSING: "true"   # always allow fallback
+```
+
+<!-- markdownlint-enable MD013 -->
+
+> **Tip:** Setting `CREATE_MISSING` to `true` in your workflow means
+> stuck PRs self-heal on the next `synchronize` event without requiring
+> a comment directive.
+
 ## Close Merged PRs Feature
 
 GitHub2Gerrit now includes **automatic PR closure** when Gerrit merges changes
@@ -1526,7 +1636,9 @@ requiring manual configuration per PR or user.
   - `src/github2gerrit/gitutils.py` (subprocess and git helpers)
 - Linting and type checking
   - Ruff and MyPy use settings in `pyproject.toml`.
-  - Run from pre‑commit hooks and CI.
+  - Run from [prek](https://github.com/j178/prek) hooks and CI.
+  - prek is a faster, Rust-based drop-in replacement for pre-commit
+    that reads the existing `.pre-commit-config.yaml` unchanged.
 - Tests
   - Pytest with coverage targets around 80%.
   - Add unit and integration tests for each feature.
@@ -1536,6 +1648,10 @@ requiring manual configuration per PR or user.
 - Install `uv` and run:
   - `uv pip install --system .`
   - `uv run github2gerrit --help`
+- Install prek hooks:
+  - `uv tool install prek && prek install -f`
+- Run all checks (including tests) manually:
+  - `prek run --all-files`
 - Run tests:
   - `uv run pytest -q`
 - Lint and type check:

{github2gerrit-1.0.7 → github2gerrit-1.0.9}/README.md

@@ -101,6 +101,117 @@ If UPDATE fails to find existing change:
    To create a new change, trigger the 'opened' workflow action.
 ```
 
+## PR Comment Commands
+
+GitHub2Gerrit supports an extensible set of directives issued through
+pull request comments. Add a comment containing `@github2gerrit`
+followed by a command phrase and the tool will act on it during
+the next workflow run.
+
+### Command Format
+
+<!-- markdownlint-disable MD013 -->
+
+```text
+@github2gerrit <command>
+```
+
+<!-- markdownlint-enable MD013 -->
+
+- Commands are **case-insensitive** — `@github2gerrit Create Missing Change`
+  works the same as `@github2gerrit create missing change`.
+- Only the **latest** occurrence of each command takes effect when the same
+  command appears in more than one comment.
+- The tool logs unrecognised directives at debug level and ignores them.
+
+### Available Commands
+
+<!-- markdownlint-disable MD013 MD060 -->
+
+| Command | Aliases | Description |
+| --- | --- | --- |
+| `create missing change` | `create-missing`, `create missing` | Create a Gerrit change when an UPDATE operation cannot find an existing one |
+
+<!-- markdownlint-enable MD013 MD060 -->
+
+### Create Missing Change
+
+When a PR `synchronize` event fires, GitHub2Gerrit treats it as an
+**UPDATE** operation and expects a Gerrit change to exist. If the
+original `opened` event failed (for example due to a bug or transient
+error), no Gerrit change exists and every following update fails with:
+
+```text
+❌ UPDATE FAILED: Cannot update non-existent Gerrit change
+```
+
+The **create missing change** command resolves this without manual
+intervention in Gerrit. Two mechanisms trigger it:
+
+#### 1. PR Comment Directive
+
+Add a comment on the stuck pull request:
+
+```text
+@github2gerrit create missing change
+```
+
+Then re-trigger the workflow (push a trivial change or re-run the
+workflow manually). GitHub2Gerrit detects the directive, switches
+from UPDATE to CREATE mode, and pushes a new Gerrit change.
+
+#### 2. CLI Flag
+
+Outside GitHub Actions you can pass the flag directly:
+
+```shell
+github2gerrit \
+  --create-missing \
+  https://github.com/MyOrg/my-repo/pull/42
+```
+
+Or set the environment variable:
+
+```shell
+export CREATE_MISSING=true
+github2gerrit https://github.com/MyOrg/my-repo/pull/42
+```
+
+#### What Happens During Fallback
+
+1. The tool attempts the normal UPDATE flow and finds no existing
+   Gerrit change.
+2. It checks for `--create-missing` **or** scans PR comments for the
+   `@github2gerrit create missing change` directive.
+3. If authorised, the operation mode switches from UPDATE to CREATE.
+4. The tool posts a notice on the PR:
+
+   ```text
+   🔄 GitHub2Gerrit: No existing Gerrit change found for this PR.
+   Creating a new Gerrit change (fallback from UPDATE operation).
+   ```
+
+5. The pipeline continues as a normal CREATE — preparing commits,
+   pushing to Gerrit, posting the change URL back on the PR.
+
+#### GitHub Actions Workflow Example
+
+<!-- markdownlint-disable MD013 -->
+
+```yaml
+- name: Submit PR to Gerrit
+  uses: lfreleng-actions/github2gerrit-action@main
+  with:
+    GERRIT_SSH_PRIVKEY_G2G: ${{ secrets.GERRIT_SSH_PRIVKEY_G2G }}
+    CREATE_MISSING: "true"   # always allow fallback
+```
+
+<!-- markdownlint-enable MD013 -->
+
+> **Tip:** Setting `CREATE_MISSING` to `true` in your workflow means
+> stuck PRs self-heal on the next `synchronize` event without requiring
+> a comment directive.
+
 ## Close Merged PRs Feature
 
 GitHub2Gerrit now includes **automatic PR closure** when Gerrit merges changes
@@ -1480,7 +1591,9 @@ requiring manual configuration per PR or user.
   - `src/github2gerrit/gitutils.py` (subprocess and git helpers)
 - Linting and type checking
   - Ruff and MyPy use settings in `pyproject.toml`.
-  - Run from pre‑commit hooks and CI.
+  - Run from [prek](https://github.com/j178/prek) hooks and CI.
+  - prek is a faster, Rust-based drop-in replacement for pre-commit
+    that reads the existing `.pre-commit-config.yaml` unchanged.
 - Tests
   - Pytest with coverage targets around 80%.
   - Add unit and integration tests for each feature.
@@ -1490,6 +1603,10 @@ requiring manual configuration per PR or user.
 - Install `uv` and run:
   - `uv pip install --system .`
   - `uv run github2gerrit --help`
+- Install prek hooks:
+  - `uv tool install prek && prek install -f`
+- Run all checks (including tests) manually:
+  - `prek run --all-files`
 - Run tests:
   - `uv run pytest -q`
 - Lint and type check:

{github2gerrit-1.0.7 → github2gerrit-1.0.9}/action.yaml

@@ -129,6 +129,14 @@ inputs:
       (format: [{"key": "username", "value": "ISSUE-ID"}])
     required: false
     default: "[]"
+  COMMIT_RULES_JSON:
+    description: >-
+      JSON object defining commit message rules with per-project and
+      per-actor overrides. Supports arbitrary label-value pairs placed
+      in the commit body or trailer block.
+      (see: docs/COMMIT_RULES.md)
+    required: false
+    default: ""
   AUTOMATION_ONLY:
     description: "Only accept pull requests from known automation tools"
     required: false
@@ -141,6 +149,10 @@ inputs:
     description: "Abandon Gerrit changes when their GitHub PRs are closed"
     required: false
     default: "true"
+  CREATE_MISSING:
+    description: "Create a Gerrit change when an UPDATE operation cannot find an existing one"
+    required: false
+    default: "false"
 
 outputs:
   gerrit_change_request_url:
@@ -164,7 +176,7 @@ runs:
 
     - name: "Setup uv"
       # yamllint disable-line rule:line-length
-      uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b  # v7.3.0
+      uses: astral-sh/setup-uv@e06108dd0aef18192324c70427afc47652e63a82  # v7.5.0
       with:
         enable-cache: false
 
@@ -290,6 +302,7 @@ runs:
         ALLOW_DUPLICATES: ${{ inputs.ALLOW_DUPLICATES }}
         ISSUE_ID: ${{ inputs.ISSUE_ID }}
         ISSUE_ID_LOOKUP_JSON: ${{ inputs.ISSUE_ID_LOOKUP_JSON }}
+        COMMIT_RULES_JSON: ${{ inputs.COMMIT_RULES_JSON }}
         CI_TESTING: ${{ inputs.CI_TESTING }}
         CLOSE_MERGED_PRS: ${{ inputs.CLOSE_MERGED_PRS }}
         FORCE: ${{ inputs.FORCE }}
@@ -300,6 +313,7 @@ runs:
         AUTOMATION_ONLY: ${{ inputs.AUTOMATION_ONLY }}
         CLEANUP_ABANDONED: ${{ inputs.CLEANUP_ABANDONED }}
         CLEANUP_GERRIT: ${{ inputs.CLEANUP_GERRIT }}
+        CREATE_MISSING: ${{ inputs.CREATE_MISSING }}
 
         # Optional Gerrit overrides (when .gitreview is missing)
         GERRIT_SERVER: ${{ inputs.GERRIT_SERVER }}

github2gerrit-1.0.9/docs/COMMIT_RULES.md

@@ -0,0 +1,255 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2025 The Linux Foundation -->
+
+# Commit Rules (`COMMIT_RULES_JSON`)
+
+The **commit rules** feature provides a flexible, JSON-driven mechanism for
+injecting arbitrary lines into commit messages submitted to Gerrit. It
+generalises the existing `ISSUE_ID` / `ISSUE_ID_LOOKUP_JSON` support to handle
+per-project requirements such as FD.io VPP's mandatory `Type:` field.
+
+## Quick Start
+
+Set the `COMMIT_RULES_JSON` GitHub Actions variable (organisation or
+repository level) to a JSON object describing the rules:
+
+```yaml
+# .github/workflows/g2g.yml
+jobs:
+  submit:
+    steps:
+      - uses: lfreleng-actions/github2gerrit-action@main
+        with:
+          COMMIT_RULES_JSON: ${{ vars.COMMIT_RULES_JSON }}
+          # ... other inputs ...
+```
+
+## JSON Schema
+
+The top-level object has three optional sections:
+
+| Section    | Type                          | Description                                    |
+|------------|-------------------------------|------------------------------------------------|
+| `defaults` | `array` of rule objects       | Baseline rules applied to every commit.        |
+| `projects` | `object` (project → rules[])  | Per-Gerrit-project overrides.                  |
+| `actors`   | `object` (actor → rules[])    | Per-GitHub-actor overrides (e.g. bots).        |
+
+### Rule Object
+
+Each rule object describes a single line to insert into the commit message:
+
+| Field       | Type     | Required | Default        | Description                                                                |
+|-------------|----------|----------|----------------|----------------------------------------------------------------------------|
+| `key`       | `string` | Yes      | —              | The label name (e.g. `Type`, `Issue-ID`, `Ticket`).                        |
+| `value`     | `string` | Yes      | —              | The value to insert.                                                       |
+| `location`  | `string` | No       | `"trailer"`    | Where to place the line — `"trailer"` or `"body"`.                         |
+| `separator` | `string` | No       | `"blank_line"` | Separation style when `location` is `"body"` — `"blank_line"` or `"none"`. |
+
+### Locations
+
+- **`trailer`** — places the line in the Git trailer block at the end of
+  the commit message, alongside `Change-Id`, `Signed-off-by`, etc.
+- **`body`** — places the line in the commit body, before the trailer
+  block. Fields like VPP's `Type:` need this location because Gerrit
+  server-side hooks expect them in the body rather than the trailer section.
+
+### Separators (body location only)
+
+- **`blank_line`** (default) — inserts a blank line before the new
+  content, matching the conventional VPP commit style.
+- **`none`** — appends the line directly after the existing body text
+  without extra blank lines.
+
+## Resolution Precedence
+
+The engine resolves rules in this order when building the commit message
+(last writer wins for a given `key`):
+
+1. **`defaults`** — baseline rules for all projects and actors.
+2. **`projects[<gerrit_project>]`** — overrides defaults for the matching
+   Gerrit project (from `.gitreview` or `GERRIT_PROJECT`).
+3. **`actors[<github_actor>]`** — overrides everything for the matching
+   GitHub actor (from `GITHUB_ACTOR`).
+
+The existing `ISSUE_ID` input always takes priority over any `Issue-ID`
+rule from commit rules. Both mechanisms can coexist safely.
+
+## Examples
+
+### FD.io (VPP + CSIT on the same Gerrit server)
+
+VPP requires a `Type:` field in the commit body; CSIT does not.
+Both projects need `Issue-ID` in the trailer block.
+
+```json
+{
+  "defaults": [
+    {
+      "key": "Issue-ID",
+      "value": "CIMAN-33",
+      "location": "trailer"
+    }
+  ],
+  "projects": {
+    "vpp": [
+      {
+        "key": "Type",
+        "value": "ci",
+        "location": "body",
+        "separator": "blank_line"
+      },
+      {
+        "key": "Issue-ID",
+        "value": "CIMAN-33",
+        "location": "trailer"
+      }
+    ],
+    "hicn": [
+      {
+        "key": "Type",
+        "value": "ci",
+        "location": "body",
+        "separator": "blank_line"
+      }
+    ]
+  },
+  "actors": {
+    "dependabot[bot]": [
+      {
+        "key": "Type",
+        "value": "ci",
+        "location": "body"
+      },
+      {
+        "key": "Issue-ID",
+        "value": "CIMAN-33",
+        "location": "trailer"
+      }
+    ],
+    "renovate[bot]": [
+      {
+        "key": "Issue-ID",
+        "value": "CIMAN-44",
+        "location": "trailer"
+      }
+    ]
+  }
+}
+```
+
+**Result for VPP + dependabot:**
+
+```text
+gha: update actions/checkout from v3 to v4
+
+Type: ci
+
+Issue-ID: CIMAN-33
+Change-Id: I1234567890abcdef...
+Signed-off-by: dependabot[bot] <support@github.com>
+```
+
+**Result for CSIT + human user:**
+
+```text
+fix: correct test assertion
+
+Issue-ID: CIMAN-33
+Change-Id: I1234567890abcdef...
+Signed-off-by: Jane Doe <jane@example.com>
+```
+
+### ONAP (Issue-ID only)
+
+ONAP projects only need `Issue-ID` in the trailer:
+
+```json
+{
+  "actors": {
+    "dependabot[bot]": [
+      {
+        "key": "Issue-ID",
+        "value": "CIMAN-33"
+      }
+    ]
+  }
+}
+```
+
+### Extra body fields
+
+Some projects need more than one body field:
+
+```json
+{
+  "projects": {
+    "vpp": [
+      {
+        "key": "Type",
+        "value": "ci",
+        "location": "body",
+        "separator": "blank_line"
+      },
+      {
+        "key": "Ticket",
+        "value": "VPP-2088",
+        "location": "body",
+        "separator": "none"
+      }
+    ]
+  }
+}
+```
+
+**Result:**
+
+```text
+gha: update dependency versions
+
+Type: ci
+Ticket: VPP-2088
+
+Change-Id: I1234567890abcdef...
+Signed-off-by: bot <bot@example.com>
+```
+
+## CLI Usage
+
+You can also pass the commit rules JSON via the command line:
+
+```bash
+github2gerrit --commit-rules '{"defaults": [...]}' \
+  https://github.com/org/repo/pull/123
+```
+
+Or via the environment variable:
+
+```bash
+export COMMIT_RULES_JSON='{"defaults": [...]}'
+github2gerrit https://github.com/org/repo/pull/123
+```
+
+## Interaction with ISSUE_ID / ISSUE_ID_LOOKUP_JSON
+
+The existing `ISSUE_ID` and `ISSUE_ID_LOOKUP_JSON` inputs continue to
+work unchanged. When both mechanisms specify an `Issue-ID`:
+
+1. An explicit `ISSUE_ID` input (or a value resolved from
+   `ISSUE_ID_LOOKUP_JSON`) **always wins**.
+2. If `ISSUE_ID` is empty, the engine applies the `Issue-ID` rule from
+   `COMMIT_RULES_JSON` instead.
+
+This means you can safely enable `COMMIT_RULES_JSON` for an organisation
+without breaking workflows that already set `ISSUE_ID` directly.
+
+## Validation and Error Handling
+
+- Invalid JSON produces a warning but does **not** fail the workflow
+  (matching the existing `ISSUE_ID_LOOKUP_JSON` convention).
+- Individual rule entries with missing or invalid `key`/`value` fields
+  produce a warning and the engine skips them; valid entries in the same
+  document still apply.
+- Unknown `location` values default to `"trailer"` with a warning.
+- Unknown `separator` values default to `"blank_line"` with a warning.
+- Duplicate lines are automatically detected and skipped (both in body
+  and trailer locations).

{github2gerrit-1.0.7 → github2gerrit-1.0.9}/pyproject.toml

@@ -102,7 +102,6 @@ dev = [
   # Type checking helpers
   "pytest-mock>=3.15.1",
   "types-requests>=2.31.0",
-  "types-click>=7.1.8",
   "types-urllib3>=1.26.25.14",
 ]
 
@@ -230,7 +229,6 @@ directory = "coverage_html_report"
 minversion = "8.0"
 addopts = "-ra -q --cov=github2gerrit --cov-report=term-missing --cov-report=html"
 testpaths = ["tests"]
-asyncio_default_fixture_loop_scope = "function"
 markers = [
     "integration: marks tests as integration tests (deselect with '-m \"not integration\"')",
 ]