<!--
SPDX-License-Identifier: Apache-2.0
SPDX-FileCopyrightText: 2025 The Linux Foundation
-->
# github2gerrit-python
Submit a GitHub pull request to a Gerrit repository, implemented in Python.
This action is a drop‑in replacement for the shell‑based
`lfit/github2gerrit` composite action. It mirrors the same inputs,
outputs, environment variables, and secrets so you can adopt it without
changing existing configuration in your organizations.
The tool expects a `.gitreview` file in the repository to derive Gerrit
connection details and the destination project. It uses `git` over SSH
and `git-review` semantics to push to `refs/for/<branch>` and relies on
Gerrit `Change-Id` trailers to create or update changes.
Note: the initial versions focus on compatibility and clear logging.
The behavior matches the existing action, and this implementation
refactors it to Python with typed modules and test support.
## How it works (high level)
- Discover pull request context and inputs.
- Check for duplicate changes to prevent spam from automated tools.
- Read `.gitreview` for Gerrit host, port, and project.
- Set up `git` user config and SSH for Gerrit.
- Prepare commits:
- one‑by‑one cherry‑pick with `Change-Id` trailers, or
- squash into a single commit and keep or reuse `Change-Id`.
- Optionally replace the commit message with PR title and body.
- Push with a topic to `refs/for/<branch>` using `git-review` behavior.
- Query Gerrit for the resulting URL, change number, and patchset SHA.
- Add a back‑reference comment in Gerrit to the GitHub PR and run URL.
- Comment on the GitHub PR with the Gerrit change URL(s).
- Optionally close the PR (mirrors the shell action policy).
## Requirements
- Repository contains a `.gitreview` file. If you cannot provide it,
you must pass `GERRIT_SERVER`, `GERRIT_SERVER_PORT`, and
`GERRIT_PROJECT` via the reusable workflow interface.
- SSH key for Gerrit and known hosts are available to the workflow.
- The default `GITHUB_TOKEN` is available for PR metadata and comments.
- The workflow grants permissions required for PR interactions:
- `pull-requests: write` (to comment on and close PRs)
- `issues: write` (to create PR comments via the Issues API)
- The workflow runs with `pull_request_target` or via
`workflow_dispatch` using a valid PR context.
## Duplicate detection
By default, the tool checks for duplicate changes to prevent spam
submissions from automated tools like Dependabot. It compares PR titles,
content, and files changed against recent PRs (last 7 days) and will
exit with an error when it finds duplicates.
### Examples of detected duplicates
- Identical Dependabot PRs: "Bump package from 1.0 to 1.1"
- Sequential dependency updates: "Bump package 1.0→1.1", "Bump package 1.1→1.2"
- Similar bug fixes with slightly different wording
### Allowing duplicates
Use `--allow-duplicates` or set `ALLOW_DUPLICATES=true` to override:
```bash
# CLI usage
github2gerrit --allow-duplicates https://github.com/org/repo
# GitHub Actions
uses: onap/github2gerrit-python@main
with:
ALLOW_DUPLICATES: 'true'
```
When allowed, duplicates generate warnings but processing continues.
The tool exits with code 3 when it detects duplicates and they are not allowed.
## Usage
This action runs as part of a workflow that triggers on
`pull_request_target` and also supports manual runs via
`workflow_dispatch`.
Minimal example:
```yaml
name: github2gerrit-python
on:
pull_request_target:
types: [opened, reopened, edited, synchronize]
workflow_dispatch:
permissions:
contents: read
pull-requests: write
issues: write
jobs:
submit-to-gerrit:
runs-on: ubuntu-latest
steps:
- name: Submit PR to Gerrit
id: g2g
uses: lfit/github2gerrit-python@main
with:
SUBMIT_SINGLE_COMMITS: "false"
USE_PR_AS_COMMIT: "false"
FETCH_DEPTH: "10"
GERRIT_KNOWN_HOSTS: ${{ vars.GERRIT_KNOWN_HOSTS }}
GERRIT_SSH_PRIVKEY_G2G: ${{ secrets.GERRIT_SSH_PRIVKEY_G2G }}
GERRIT_SSH_USER_G2G: ${{ vars.GERRIT_SSH_USER_G2G }}
GERRIT_SSH_USER_G2G_EMAIL: ${{ vars.GERRIT_SSH_USER_G2G_EMAIL }}
ORGANIZATION: ${{ github.repository_owner }}
REVIEWERS_EMAIL: ""
```
The action reads `.gitreview`. If `.gitreview` is absent, you must
supply Gerrit connection details through a reusable workflow or by
setting the corresponding environment variables before invoking the
action. The shell action enforces `.gitreview` for the composite
variant; this Python action mirrors that behavior for compatibility.
## Command Line Usage and Debugging
### Direct Command Line Usage
You can run the tool directly from the command line to process GitHub pull requests:
```bash
# Process a specific pull request
github2gerrit https://github.com/owner/repo/pull/123
# Process all open pull requests in a repository
github2gerrit https://github.com/owner/repo
# Run in CI mode (reads from environment variables)
github2gerrit
```
### Available Options
```bash
github2gerrit --help
```
Key options include:
- `--verbose` / `-v`: Enable verbose debug logging
- `--dry-run`: Check configuration without making changes
- `--submit-single-commits`: Submit each commit individually
- `--use-pr-as-commit`: Use PR title/body as commit message
- `--preserve-github-prs`: Don't close GitHub PRs after submission
### Debugging and Troubleshooting
When encountering issues, enable verbose logging to see detailed execution:
```bash
# Using the CLI flag
github2gerrit --verbose https://github.com/owner/repo/pull/123
# Using environment variable
G2G_LOG_LEVEL=DEBUG github2gerrit https://github.com/owner/repo/pull/123
# Alternative environment variable
G2G_VERBOSE=true github2gerrit https://github.com/owner/repo/pull/123
```
Debug output includes:
- Git command execution and output
- SSH connection attempts
- Gerrit API interactions
- Branch resolution logic
- Change-Id processing
Common issues and solutions:
1. **SSH Permission Denied**: Ensure `GERRIT_SSH_PRIVKEY_G2G` and
`GERRIT_KNOWN_HOSTS` are properly set
2. **Branch Not Found**: Check that the target branch exists in both GitHub and Gerrit
3. **Change-Id Issues**: Enable debug logging to see Change-Id generation and validation
4. **Gerrit API Errors**: Verify Gerrit server connectivity and project permissions
### Environment Variables
The tool respects these environment variables for configuration:
- `G2G_LOG_LEVEL`: Set to `DEBUG` for verbose output (default: `INFO`)
- `G2G_VERBOSE`: Set to `true` to enable debug logging
- `GERRIT_SSH_PRIVKEY_G2G`: SSH private key content
- `GERRIT_KNOWN_HOSTS`: SSH known hosts entries
- `GERRIT_SSH_USER_G2G`: Gerrit SSH username
- `DRY_RUN`: Set to `true` for check mode
## Advanced usage
You can explicitly install the SSH key and provide a custom SSH configuration
before invoking this action. This is useful when:
- You want to override the port/host used by SSH
- You need to define host aliases or SSH options
- Your Gerrit instance uses a non-standard HTTP base path (e.g. /r)
Example:
```yaml
name: github2gerrit-python (advanced)
on:
pull_request_target:
types: [opened, reopened, edited, synchronize]
workflow_dispatch:
permissions:
contents: read
pull-requests: write
issues: write
jobs:
submit-to-gerrit:
runs-on: ubuntu-latest
steps:
- name: Install SSH key and custom SSH config
<!-- markdownlint-disable-next-line MD013 -->
uses: shimataro/ssh-key-action@d4fffb50872869abe2d9a9098a6d9c5aa7d16be4 # v2.7.0
with:
key: ${{ secrets.GERRIT_SSH_PRIVKEY_G2G }}
name: "id_rsa"
known_hosts: ${{ vars.GERRIT_KNOWN_HOSTS }}
config: |
Host ${{ vars.GERRIT_SERVER }}
User ${{ vars.GERRIT_SSH_USER_G2G }}
Port ${{ vars.GERRIT_SERVER_PORT }}
PubkeyAcceptedKeyTypes +ssh-rsa
IdentityFile ~/.ssh/id_rsa
- name: Submit PR to Gerrit (with explicit overrides)
id: g2g
uses: lfit/github2gerrit-python@main
with:
# Behavior
SUBMIT_SINGLE_COMMITS: "false"
USE_PR_AS_COMMIT: "false"
FETCH_DEPTH: "10"
# Required SSH/identity
GERRIT_KNOWN_HOSTS: ${{ vars.GERRIT_KNOWN_HOSTS }}
GERRIT_SSH_PRIVKEY_G2G: ${{ secrets.GERRIT_SSH_PRIVKEY_G2G }}
GERRIT_SSH_USER_G2G: ${{ vars.GERRIT_SSH_USER_G2G }}
GERRIT_SSH_USER_G2G_EMAIL: ${{ vars.GERRIT_SSH_USER_G2G_EMAIL }}
# Optional overrides when .gitreview is missing or to force values
GERRIT_SERVER: ${{ vars.GERRIT_SERVER }}
GERRIT_SERVER_PORT: ${{ vars.GERRIT_SERVER_PORT }}
GERRIT_PROJECT: ${{ vars.GERRIT_PROJECT }}
# Optional Gerrit REST base path and credentials (if required)
# e.g. '/r' for some deployments
GERRIT_HTTP_BASE_PATH: ${{ vars.GERRIT_HTTP_BASE_PATH }}
GERRIT_HTTP_USER: ${{ vars.GERRIT_HTTP_USER }}
GERRIT_HTTP_PASSWORD: ${{ secrets.GERRIT_HTTP_PASSWORD }}
ORGANIZATION: ${{ github.repository_owner }}
REVIEWERS_EMAIL: ""
```
Notes:
- If both this step and the action define SSH configuration, the last
configuration applied in the runner wins.
- For most users, you can rely on the action’s built-in SSH setup. Use this
advanced configuration when you need custom SSH behavior or hosts.
## GitHub Enterprise support
- Direct-URL mode accepts enterprise GitHub hosts when explicitly enabled.
Default: off (use github.com by default). Enable via the CLI flag
--allow-ghe-urls or by setting ALLOW_GHE_URLS="true".
- In GitHub Actions, this action works with GitHub Enterprise when the
workflow runs in that enterprise environment and provides a valid
GITHUB_TOKEN. For direct-URL runs outside Actions, ensure ORGANIZATION
and GITHUB_REPOSITORY reflect the target repository.
## Inputs
All inputs are strings, matching the composite action.
- SUBMIT_SINGLE_COMMITS
- Submit one commit at a time to Gerrit. Default: "false".
- USE_PR_AS_COMMIT
- Use PR title and body as the commit message. Default: "false".
- FETCH_DEPTH
- Depth used when checking out the repository. Default: "10".
- GERRIT_KNOWN_HOSTS
- SSH known hosts content for the Gerrit host. Required.
- GERRIT_SSH_PRIVKEY_G2G
- SSH private key for Gerrit. Required.
- GERRIT_SSH_USER_G2G
- Gerrit SSH username. Required.
- GERRIT_SSH_USER_G2G_EMAIL
- Gerrit SSH user email (used for commit identity). Required.
- ORGANIZATION
- Organization name, defaults to `github.repository_owner`.
- REVIEWERS_EMAIL
- Comma separated reviewer emails. If empty, defaults to
`GERRIT_SSH_USER_G2G_EMAIL`.
- ALLOW_GHE_URLS
- Allow non-github.com GitHub Enterprise URLs in direct URL mode. Default: "false".
- Set to "true" to allow non-github.com enterprise hosts.
Optional inputs when `.gitreview` is not present (parity with
the reusable workflow):
- GERRIT_SERVER
- Gerrit host, e.g. `git.opendaylight.org`. Default: "".
- GERRIT_SERVER_PORT
- Gerrit port, default "29418".
- GERRIT_PROJECT
- Gerrit project name, e.g. `releng/builder`. Default: "".
## Outputs
- url
- Gerrit change URL(s). Multi‑line when the action submits more than one change.
- change_number
- Gerrit change number(s). Multi‑line when the action submits more than one change.
These outputs mirror the composite action. They are also exported into
the environment as:
- GERRIT_CHANGE_REQUEST_URL
- GERRIT_CHANGE_REQUEST_NUM
## Behavior details
- Branch resolution
- Uses `GITHUB_BASE_REF` as the target branch for Gerrit, or defaults
to `master` when unset, matching the existing workflow.
- Topic naming
- Uses `GH-<repo>-<pr-number>` where `<repo>` replaces slashes with
hyphens.
- GitHub Enterprise support
- Direct URL mode accepts enterprise GitHub hosts when explicitly enabled
(default: off; use github.com by default). Enable via --allow-ghe-urls or
ALLOW_GHE_URLS="true". The tool determines the GitHub API base URL from
GITHUB_API_URL or GITHUB_SERVER_URL/api/v3.
- Change‑Id handling
- Single commits: the process amends each cherry‑picked commit to include a
`Change-Id`. The tool collects these values for querying.
- Squashed: collects trailers from original commits, preserves
`Signed-off-by`, and reuses the `Change-Id` when PRs reopen or synchronize.
- Reviewers
- If empty, defaults to the Gerrit SSH user email.
- Comments
- Adds a back‑reference comment in Gerrit with the GitHub PR and run
URL. Adds a comment on the GitHub PR with the Gerrit change URL(s).
- Closing PRs
- On `pull_request_target`, the workflow may close the PR after submission to
match the shell action’s behavior.
## Security notes
- Do not hardcode secrets or keys. Provide the private key via the
workflow secrets and known hosts via repository or org variables.
- SSH handling is non-invasive: the tool creates temporary SSH files in
the workspace without modifying user SSH configuration or keys.
- SSH agent scanning prevention uses `IdentitiesOnly=yes` to avoid
unintended key usage (e.g., signing keys requiring biometric auth).
- Temporary SSH files are automatically cleaned up after execution.
- All external calls should use retries and clear error reporting.
## Development
This repository follows the guidelines in `CLAUDE.md`.
- Language and CLI
- Python 3.11. The CLI uses Typer.
- Packaging
- `pyproject.toml` with PDM backend. Use `uv` to install and run.
- Structure
- `src/github2gerrit_python/cli.py` (CLI entrypoint)
- `src/github2gerrit_python/core.py` (orchestration)
- `src/github2gerrit_python/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.
- Tests
- Pytest with coverage targets around 80%.
- Add unit and integration tests for each feature.
### Local setup
- Install `uv` and run:
- `uv pip install --system .`
- `uv run github2gerrit --help`
- Run tests:
- `uv run pytest -q`
- Lint and type check:
- `uv run ruff check .`
- `uv run black --check .`
- `uv run mypy src`
### Notes on parity
- Inputs, outputs, and environment usage match the shell action.
- The action assumes the same GitHub variables and secrets are present.
- Where the shell action uses tools such as `jq` and `gh`, the Python
version uses library calls and subprocess as appropriate, with retries
and clear logging.
## License
Apache License 2.0. See `LICENSE` for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "github2gerrit-python",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.11",
"maintainer_email": null,
"keywords": "github, gerrit, ci, actions, typer, cli",
"author": null,
"author_email": "Matthew Watkins <mwatkins@linuxfoundation.org>",
"download_url": "https://files.pythonhosted.org/packages/71/b8/3d4df1b12db45c74326a5369bd5f40a678617f1af919b1bff57f716b5d06/github2gerrit_python-0.1.0.tar.gz",
"platform": null,
"description": "<!--\nSPDX-License-Identifier: Apache-2.0\nSPDX-FileCopyrightText: 2025 The Linux Foundation\n-->\n\n# github2gerrit-python\n\nSubmit a GitHub pull request to a Gerrit repository, implemented in Python.\n\nThis action is a drop\u2011in replacement for the shell\u2011based\n`lfit/github2gerrit` composite action. It mirrors the same inputs,\noutputs, environment variables, and secrets so you can adopt it without\nchanging existing configuration in your organizations.\n\nThe tool expects a `.gitreview` file in the repository to derive Gerrit\nconnection details and the destination project. It uses `git` over SSH\nand `git-review` semantics to push to `refs/for/<branch>` and relies on\nGerrit `Change-Id` trailers to create or update changes.\n\nNote: the initial versions focus on compatibility and clear logging.\nThe behavior matches the existing action, and this implementation\nrefactors it to Python with typed modules and test support.\n\n## How it works (high level)\n\n- Discover pull request context and inputs.\n- Check for duplicate changes to prevent spam from automated tools.\n- Read `.gitreview` for Gerrit host, port, and project.\n- Set up `git` user config and SSH for Gerrit.\n- Prepare commits:\n - one\u2011by\u2011one cherry\u2011pick with `Change-Id` trailers, or\n - squash into a single commit and keep or reuse `Change-Id`.\n- Optionally replace the commit message with PR title and body.\n- Push with a topic to `refs/for/<branch>` using `git-review` behavior.\n- Query Gerrit for the resulting URL, change number, and patchset SHA.\n- Add a back\u2011reference comment in Gerrit to the GitHub PR and run URL.\n- Comment on the GitHub PR with the Gerrit change URL(s).\n- Optionally close the PR (mirrors the shell action policy).\n\n## Requirements\n\n- Repository contains a `.gitreview` file. If you cannot provide it,\n you must pass `GERRIT_SERVER`, `GERRIT_SERVER_PORT`, and\n `GERRIT_PROJECT` via the reusable workflow interface.\n- SSH key for Gerrit and known hosts are available to the workflow.\n- The default `GITHUB_TOKEN` is available for PR metadata and comments.\n- The workflow grants permissions required for PR interactions:\n - `pull-requests: write` (to comment on and close PRs)\n - `issues: write` (to create PR comments via the Issues API)\n- The workflow runs with `pull_request_target` or via\n `workflow_dispatch` using a valid PR context.\n\n## Duplicate detection\n\nBy default, the tool checks for duplicate changes to prevent spam\nsubmissions from automated tools like Dependabot. It compares PR titles,\ncontent, and files changed against recent PRs (last 7 days) and will\nexit with an error when it finds duplicates.\n\n### Examples of detected duplicates\n\n- Identical Dependabot PRs: \"Bump package from 1.0 to 1.1\"\n- Sequential dependency updates: \"Bump package 1.0\u21921.1\", \"Bump package 1.1\u21921.2\"\n- Similar bug fixes with slightly different wording\n\n### Allowing duplicates\n\nUse `--allow-duplicates` or set `ALLOW_DUPLICATES=true` to override:\n\n```bash\n# CLI usage\ngithub2gerrit --allow-duplicates https://github.com/org/repo\n\n# GitHub Actions\nuses: onap/github2gerrit-python@main\nwith:\n ALLOW_DUPLICATES: 'true'\n```\n\nWhen allowed, duplicates generate warnings but processing continues.\nThe tool exits with code 3 when it detects duplicates and they are not allowed.\n\n## Usage\n\nThis action runs as part of a workflow that triggers on\n`pull_request_target` and also supports manual runs via\n`workflow_dispatch`.\n\nMinimal example:\n\n```yaml\nname: github2gerrit-python\n\non:\n pull_request_target:\n types: [opened, reopened, edited, synchronize]\n workflow_dispatch:\n\npermissions:\n contents: read\n pull-requests: write\n issues: write\n\njobs:\n submit-to-gerrit:\n runs-on: ubuntu-latest\n steps:\n - name: Submit PR to Gerrit\n id: g2g\n uses: lfit/github2gerrit-python@main\n with:\n SUBMIT_SINGLE_COMMITS: \"false\"\n USE_PR_AS_COMMIT: \"false\"\n FETCH_DEPTH: \"10\"\n GERRIT_KNOWN_HOSTS: ${{ vars.GERRIT_KNOWN_HOSTS }}\n GERRIT_SSH_PRIVKEY_G2G: ${{ secrets.GERRIT_SSH_PRIVKEY_G2G }}\n GERRIT_SSH_USER_G2G: ${{ vars.GERRIT_SSH_USER_G2G }}\n GERRIT_SSH_USER_G2G_EMAIL: ${{ vars.GERRIT_SSH_USER_G2G_EMAIL }}\n ORGANIZATION: ${{ github.repository_owner }}\n REVIEWERS_EMAIL: \"\"\n```\n\nThe action reads `.gitreview`. If `.gitreview` is absent, you must\nsupply Gerrit connection details through a reusable workflow or by\nsetting the corresponding environment variables before invoking the\naction. The shell action enforces `.gitreview` for the composite\nvariant; this Python action mirrors that behavior for compatibility.\n\n## Command Line Usage and Debugging\n\n### Direct Command Line Usage\n\nYou can run the tool directly from the command line to process GitHub pull requests:\n\n```bash\n# Process a specific pull request\ngithub2gerrit https://github.com/owner/repo/pull/123\n\n# Process all open pull requests in a repository\ngithub2gerrit https://github.com/owner/repo\n\n# Run in CI mode (reads from environment variables)\ngithub2gerrit\n```\n\n### Available Options\n\n```bash\ngithub2gerrit --help\n```\n\nKey options include:\n\n- `--verbose` / `-v`: Enable verbose debug logging\n- `--dry-run`: Check configuration without making changes\n- `--submit-single-commits`: Submit each commit individually\n- `--use-pr-as-commit`: Use PR title/body as commit message\n- `--preserve-github-prs`: Don't close GitHub PRs after submission\n\n### Debugging and Troubleshooting\n\nWhen encountering issues, enable verbose logging to see detailed execution:\n\n```bash\n# Using the CLI flag\ngithub2gerrit --verbose https://github.com/owner/repo/pull/123\n\n# Using environment variable\nG2G_LOG_LEVEL=DEBUG github2gerrit https://github.com/owner/repo/pull/123\n\n# Alternative environment variable\nG2G_VERBOSE=true github2gerrit https://github.com/owner/repo/pull/123\n```\n\nDebug output includes:\n\n- Git command execution and output\n- SSH connection attempts\n- Gerrit API interactions\n- Branch resolution logic\n- Change-Id processing\n\nCommon issues and solutions:\n\n1. **SSH Permission Denied**: Ensure `GERRIT_SSH_PRIVKEY_G2G` and\n `GERRIT_KNOWN_HOSTS` are properly set\n2. **Branch Not Found**: Check that the target branch exists in both GitHub and Gerrit\n3. **Change-Id Issues**: Enable debug logging to see Change-Id generation and validation\n4. **Gerrit API Errors**: Verify Gerrit server connectivity and project permissions\n\n### Environment Variables\n\nThe tool respects these environment variables for configuration:\n\n- `G2G_LOG_LEVEL`: Set to `DEBUG` for verbose output (default: `INFO`)\n- `G2G_VERBOSE`: Set to `true` to enable debug logging\n- `GERRIT_SSH_PRIVKEY_G2G`: SSH private key content\n- `GERRIT_KNOWN_HOSTS`: SSH known hosts entries\n- `GERRIT_SSH_USER_G2G`: Gerrit SSH username\n- `DRY_RUN`: Set to `true` for check mode\n\n## Advanced usage\n\nYou can explicitly install the SSH key and provide a custom SSH configuration\nbefore invoking this action. This is useful when:\n\n- You want to override the port/host used by SSH\n- You need to define host aliases or SSH options\n- Your Gerrit instance uses a non-standard HTTP base path (e.g. /r)\n\nExample:\n\n```yaml\nname: github2gerrit-python (advanced)\n\non:\n pull_request_target:\n types: [opened, reopened, edited, synchronize]\n workflow_dispatch:\n\npermissions:\n contents: read\n pull-requests: write\n issues: write\n\njobs:\n submit-to-gerrit:\n runs-on: ubuntu-latest\n steps:\n - name: Install SSH key and custom SSH config\n <!-- markdownlint-disable-next-line MD013 -->\n uses: shimataro/ssh-key-action@d4fffb50872869abe2d9a9098a6d9c5aa7d16be4 # v2.7.0\n with:\n key: ${{ secrets.GERRIT_SSH_PRIVKEY_G2G }}\n name: \"id_rsa\"\n known_hosts: ${{ vars.GERRIT_KNOWN_HOSTS }}\n config: |\n Host ${{ vars.GERRIT_SERVER }}\n User ${{ vars.GERRIT_SSH_USER_G2G }}\n Port ${{ vars.GERRIT_SERVER_PORT }}\n PubkeyAcceptedKeyTypes +ssh-rsa\n IdentityFile ~/.ssh/id_rsa\n\n - name: Submit PR to Gerrit (with explicit overrides)\n id: g2g\n uses: lfit/github2gerrit-python@main\n with:\n # Behavior\n SUBMIT_SINGLE_COMMITS: \"false\"\n USE_PR_AS_COMMIT: \"false\"\n FETCH_DEPTH: \"10\"\n\n # Required SSH/identity\n GERRIT_KNOWN_HOSTS: ${{ vars.GERRIT_KNOWN_HOSTS }}\n GERRIT_SSH_PRIVKEY_G2G: ${{ secrets.GERRIT_SSH_PRIVKEY_G2G }}\n GERRIT_SSH_USER_G2G: ${{ vars.GERRIT_SSH_USER_G2G }}\n GERRIT_SSH_USER_G2G_EMAIL: ${{ vars.GERRIT_SSH_USER_G2G_EMAIL }}\n\n # Optional overrides when .gitreview is missing or to force values\n GERRIT_SERVER: ${{ vars.GERRIT_SERVER }}\n GERRIT_SERVER_PORT: ${{ vars.GERRIT_SERVER_PORT }}\n GERRIT_PROJECT: ${{ vars.GERRIT_PROJECT }}\n\n # Optional Gerrit REST base path and credentials (if required)\n # e.g. '/r' for some deployments\n GERRIT_HTTP_BASE_PATH: ${{ vars.GERRIT_HTTP_BASE_PATH }}\n GERRIT_HTTP_USER: ${{ vars.GERRIT_HTTP_USER }}\n GERRIT_HTTP_PASSWORD: ${{ secrets.GERRIT_HTTP_PASSWORD }}\n\n ORGANIZATION: ${{ github.repository_owner }}\n REVIEWERS_EMAIL: \"\"\n```\n\nNotes:\n\n- If both this step and the action define SSH configuration, the last\n configuration applied in the runner wins.\n- For most users, you can rely on the action\u2019s built-in SSH setup. Use this\n advanced configuration when you need custom SSH behavior or hosts.\n\n## GitHub Enterprise support\n\n- Direct-URL mode accepts enterprise GitHub hosts when explicitly enabled.\n Default: off (use github.com by default). Enable via the CLI flag\n --allow-ghe-urls or by setting ALLOW_GHE_URLS=\"true\".\n- In GitHub Actions, this action works with GitHub Enterprise when the\n workflow runs in that enterprise environment and provides a valid\n GITHUB_TOKEN. For direct-URL runs outside Actions, ensure ORGANIZATION\n and GITHUB_REPOSITORY reflect the target repository.\n\n## Inputs\n\nAll inputs are strings, matching the composite action.\n\n- SUBMIT_SINGLE_COMMITS\n - Submit one commit at a time to Gerrit. Default: \"false\".\n- USE_PR_AS_COMMIT\n - Use PR title and body as the commit message. Default: \"false\".\n- FETCH_DEPTH\n - Depth used when checking out the repository. Default: \"10\".\n- GERRIT_KNOWN_HOSTS\n - SSH known hosts content for the Gerrit host. Required.\n- GERRIT_SSH_PRIVKEY_G2G\n - SSH private key for Gerrit. Required.\n- GERRIT_SSH_USER_G2G\n - Gerrit SSH username. Required.\n- GERRIT_SSH_USER_G2G_EMAIL\n - Gerrit SSH user email (used for commit identity). Required.\n- ORGANIZATION\n - Organization name, defaults to `github.repository_owner`.\n- REVIEWERS_EMAIL\n - Comma separated reviewer emails. If empty, defaults to\n `GERRIT_SSH_USER_G2G_EMAIL`.\n- ALLOW_GHE_URLS\n - Allow non-github.com GitHub Enterprise URLs in direct URL mode. Default: \"false\".\n - Set to \"true\" to allow non-github.com enterprise hosts.\n\nOptional inputs when `.gitreview` is not present (parity with\nthe reusable workflow):\n\n- GERRIT_SERVER\n - Gerrit host, e.g. `git.opendaylight.org`. Default: \"\".\n- GERRIT_SERVER_PORT\n - Gerrit port, default \"29418\".\n- GERRIT_PROJECT\n - Gerrit project name, e.g. `releng/builder`. Default: \"\".\n\n## Outputs\n\n- url\n - Gerrit change URL(s). Multi\u2011line when the action submits more than one change.\n- change_number\n - Gerrit change number(s). Multi\u2011line when the action submits more than one change.\n\nThese outputs mirror the composite action. They are also exported into\nthe environment as:\n\n- GERRIT_CHANGE_REQUEST_URL\n- GERRIT_CHANGE_REQUEST_NUM\n\n## Behavior details\n\n- Branch resolution\n - Uses `GITHUB_BASE_REF` as the target branch for Gerrit, or defaults\n to `master` when unset, matching the existing workflow.\n- Topic naming\n - Uses `GH-<repo>-<pr-number>` where `<repo>` replaces slashes with\n hyphens.\n- GitHub Enterprise support\n - Direct URL mode accepts enterprise GitHub hosts when explicitly enabled\n (default: off; use github.com by default). Enable via --allow-ghe-urls or\n ALLOW_GHE_URLS=\"true\". The tool determines the GitHub API base URL from\n GITHUB_API_URL or GITHUB_SERVER_URL/api/v3.\n- Change\u2011Id handling\n - Single commits: the process amends each cherry\u2011picked commit to include a\n `Change-Id`. The tool collects these values for querying.\n - Squashed: collects trailers from original commits, preserves\n `Signed-off-by`, and reuses the `Change-Id` when PRs reopen or synchronize.\n- Reviewers\n - If empty, defaults to the Gerrit SSH user email.\n- Comments\n - Adds a back\u2011reference comment in Gerrit with the GitHub PR and run\n URL. Adds a comment on the GitHub PR with the Gerrit change URL(s).\n- Closing PRs\n - On `pull_request_target`, the workflow may close the PR after submission to\n match the shell action\u2019s behavior.\n\n## Security notes\n\n- Do not hardcode secrets or keys. Provide the private key via the\n workflow secrets and known hosts via repository or org variables.\n- SSH handling is non-invasive: the tool creates temporary SSH files in\n the workspace without modifying user SSH configuration or keys.\n- SSH agent scanning prevention uses `IdentitiesOnly=yes` to avoid\n unintended key usage (e.g., signing keys requiring biometric auth).\n- Temporary SSH files are automatically cleaned up after execution.\n- All external calls should use retries and clear error reporting.\n\n## Development\n\nThis repository follows the guidelines in `CLAUDE.md`.\n\n- Language and CLI\n - Python 3.11. The CLI uses Typer.\n- Packaging\n - `pyproject.toml` with PDM backend. Use `uv` to install and run.\n- Structure\n - `src/github2gerrit_python/cli.py` (CLI entrypoint)\n - `src/github2gerrit_python/core.py` (orchestration)\n - `src/github2gerrit_python/gitutils.py` (subprocess and git helpers)\n- Linting and type checking\n - Ruff and MyPy use settings in `pyproject.toml`.\n - Run from pre\u2011commit hooks and CI.\n- Tests\n - Pytest with coverage targets around 80%.\n - Add unit and integration tests for each feature.\n\n### Local setup\n\n- Install `uv` and run:\n - `uv pip install --system .`\n - `uv run github2gerrit --help`\n- Run tests:\n - `uv run pytest -q`\n- Lint and type check:\n - `uv run ruff check .`\n - `uv run black --check .`\n - `uv run mypy src`\n\n### Notes on parity\n\n- Inputs, outputs, and environment usage match the shell action.\n- The action assumes the same GitHub variables and secrets are present.\n- Where the shell action uses tools such as `jq` and `gh`, the Python\n version uses library calls and subprocess as appropriate, with retries\n and clear logging.\n\n## License\n\nApache License 2.0. See `LICENSE` for details.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Submit a GitHub pull request to a Gerrit repository.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/lfit/github2gerrit-python",
"Issues": "https://github.com/lfit/github2gerrit-python/issues",
"Repository": "https://github.com/lfit/github2gerrit-python"
},
"split_keywords": [
"github",
" gerrit",
" ci",
" actions",
" typer",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b130763d5b75c708b44bede5ed697df0aada50432a766bf60554048eb84f4c0d",
"md5": "165b9664d0f4654d22028ec06045eebb",
"sha256": "5c71dd21a81782184868c3de75ca4742be8c4b8409251c1f3d1f149bfe33c4ef"
},
"downloads": -1,
"filename": "github2gerrit_python-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "165b9664d0f4654d22028ec06045eebb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.11",
"size": 6879,
"upload_time": "2025-08-24T06:14:18",
"upload_time_iso_8601": "2025-08-24T06:14:18.907170Z",
"url": "https://files.pythonhosted.org/packages/b1/30/763d5b75c708b44bede5ed697df0aada50432a766bf60554048eb84f4c0d/github2gerrit_python-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "71b83d4df1b12db45c74326a5369bd5f40a678617f1af919b1bff57f716b5d06",
"md5": "a8bb95624af48abf258b60fbf491b6c5",
"sha256": "9e24b6892bdd673d9147799228dae9f70570d69877ef90007302c4faad028015"
},
"downloads": -1,
"filename": "github2gerrit_python-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "a8bb95624af48abf258b60fbf491b6c5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.11",
"size": 43269,
"upload_time": "2025-08-24T06:14:20",
"upload_time_iso_8601": "2025-08-24T06:14:20.189134Z",
"url": "https://files.pythonhosted.org/packages/71/b8/3d4df1b12db45c74326a5369bd5f40a678617f1af919b1bff57f716b5d06/github2gerrit_python-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-24 06:14:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lfit",
"github_project": "github2gerrit-python",
"github_not_found": true,
"lcname": "github2gerrit-python"
}
JSON
