github2gerrit 0.1.6__py3-none-any.whl → 0.1.8__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,24 @@
1
+ github2gerrit/__init__.py,sha256=N1Vj1HJ28LKCJLAynQdm5jFGQQAz9YSMzZhEfvbBgow,886
2
+ github2gerrit/cli.py,sha256=j2jdsfO3WZqHF0UIINVWJrPzMUHtIwzGKmbAhvP1Q3c,45483
3
+ github2gerrit/commit_normalization.py,sha256=u4AZigz3qOpz5XYpUOq3WUqsY-o08YrkgaT160eyIIs,16594
4
+ github2gerrit/config.py,sha256=sTiujlOjCsJbaA-Ftr5XR--9nxs7XH8uEWD-IbGqLYk,17370
5
+ github2gerrit/core.py,sha256=xSUBhB_xOpCrVbnNu2m1QqKrZJTa8zJrmEK28-ehqPg,105033
6
+ github2gerrit/duplicate_detection.py,sha256=enzLMsMQOeB5yU_iEOfTN5oGuZ0LUZNENsQ4fFnKKRg,26520
7
+ github2gerrit/external_api.py,sha256=ypMKGIsCAYTvP2u55l8X5eUC88T6EKvyZvlsAWRFVcU,17629
8
+ github2gerrit/gerrit_rest.py,sha256=NmC95hb2hLpnko8Uu3OwPEKktNv-k3qrmuA7A2q-H0Y,10562
9
+ github2gerrit/gerrit_urls.py,sha256=pw4rjIQeQ-i-vbPqsOZjZpdz7FO03pnMUMWc8L9Mcic,12893
10
+ github2gerrit/github_api.py,sha256=1cTZMunDx6_oLNR3Z__ya6vsw0_PFS5ww3jQla5SVFA,8229
11
+ github2gerrit/gitutils.py,sha256=7E-bYux4E-5IJMSxYx8U0sKzD-wkn3QyEfZ7SGHkGrY,25803
12
+ github2gerrit/models.py,sha256=sRS4rPMF_wjV19HMFTzhHXFMfsLFzm9TFb1JydJsSyQ,1875
13
+ github2gerrit/pr_content_filter.py,sha256=w4MqSZ4uLX-3Da1DL_A56zVQa7xJ4h5jHMNteOOG2AE,16896
14
+ github2gerrit/similarity.py,sha256=xPqdypI-Fmpeb74K4lcqZBxj17i8avS_x73dXckeicA,15268
15
+ github2gerrit/ssh_agent_setup.py,sha256=fvKuMdF9Hv5ioaSu_alzLcjeoQLGGFRLS2wb46KdNzE,11889
16
+ github2gerrit/ssh_common.py,sha256=f0QQmnj6yIW74N3ZjGkYmJryEstjEOmq41EIXOZdGTM,8102
17
+ github2gerrit/ssh_discovery.py,sha256=zH0tX9VN1pn8DLM1J9QQquoKBhA9gk5drXHvMSHNNLg,13021
18
+ github2gerrit/utils.py,sha256=ADE5YZe1h3PB3cgfxbsCuYU-Xs-1CMHrDHxfIdariFE,3369
19
+ github2gerrit-0.1.8.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
20
+ github2gerrit-0.1.8.dist-info/METADATA,sha256=XMojs1cbwj9CPacFK6YDE3TczE5s4tE4YFPKZXGUUIY,30930
21
+ github2gerrit-0.1.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
22
+ github2gerrit-0.1.8.dist-info/entry_points.txt,sha256=MxN2_liIKo3-xJwtAulAeS5GcOS6JS96nvwOQIkP3W8,56
23
+ github2gerrit-0.1.8.dist-info/top_level.txt,sha256=bWTYXjvuu4sSU90KLT1JlnjD7xV_iXZ-vKoulpjLTy8,14
24
+ github2gerrit-0.1.8.dist-info/RECORD,,
@@ -1,552 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: github2gerrit
3
- Version: 0.1.6
4
- Summary: Submit a GitHub pull request to a Gerrit repository.
5
- Author-email: Matthew Watkins <mwatkins@linuxfoundation.org>
6
- License-Expression: Apache-2.0
7
- Project-URL: Homepage, https://github.com//lfreleng-actions/github2gerrit
8
- Project-URL: Repository, https://github.com//lfreleng-actions/github2gerrit
9
- Project-URL: Issues, https://github.com//lfreleng-actions/github2gerrit/issues
10
- Keywords: github,gerrit,ci,actions,typer,cli
11
- Classifier: Development Status :: 4 - Beta
12
- Classifier: Environment :: Console
13
- Classifier: Intended Audience :: Developers
14
- Classifier: Programming Language :: Python :: 3
15
- Classifier: Programming Language :: Python :: 3 :: Only
16
- Classifier: Programming Language :: Python :: 3.11
17
- Classifier: Programming Language :: Python :: 3.12
18
- Classifier: Programming Language :: Python :: 3.13
19
- Classifier: Topic :: Software Development :: Build Tools
20
- Classifier: Topic :: Software Development :: Version Control
21
- Classifier: Typing :: Typed
22
- Requires-Python: <3.14,>=3.11
23
- Description-Content-Type: text/markdown
24
- License-File: LICENSE
25
- Requires-Dist: typer>=0.12.5
26
- Requires-Dist: PyGithub>=2.3.0
27
- Requires-Dist: pygerrit2>=2.0.0
28
- Requires-Dist: git-review>=2.3.1
29
- Provides-Extra: dev
30
- Requires-Dist: pytest>=8.3.2; extra == "dev"
31
- Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
32
- Requires-Dist: coverage[toml]>=7.6.1; extra == "dev"
33
- Requires-Dist: ruff>=0.6.3; extra == "dev"
34
- Requires-Dist: black>=24.8.0; extra == "dev"
35
- Requires-Dist: mypy>=1.11.2; extra == "dev"
36
- Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
37
- Requires-Dist: types-requests>=2.31.0; extra == "dev"
38
- Requires-Dist: types-click>=7.1.8; extra == "dev"
39
- Dynamic: license-file
40
-
41
- <!--
42
- SPDX-License-Identifier: Apache-2.0
43
- SPDX-FileCopyrightText: 2025 The Linux Foundation
44
- -->
45
-
46
- # github2gerrit
47
-
48
- Submit a GitHub pull request to a Gerrit repository, implemented in Python.
49
-
50
- This action is a drop‑in replacement for the shell‑based
51
- `lfit/github2gerrit` composite action. It mirrors the same inputs,
52
- outputs, environment variables, and secrets so you can adopt it without
53
- changing existing configuration in your organizations.
54
-
55
- The tool expects a `.gitreview` file in the repository to derive Gerrit
56
- connection details and the destination project. It uses `git` over SSH
57
- and `git-review` semantics to push to `refs/for/<branch>` and relies on
58
- Gerrit `Change-Id` trailers to create or update changes.
59
-
60
- Note: the initial versions focus on compatibility and clear logging.
61
- The behavior matches the existing action, and this implementation
62
- refactors it to Python with typed modules and test support.
63
-
64
- ## How it works (high level)
65
-
66
- - Discover pull request context and inputs.
67
- - Check for duplicate changes to prevent spam from automated tools.
68
- - Read `.gitreview` for Gerrit host, port, and project.
69
- - Set up `git` user config and SSH for Gerrit.
70
- - Prepare commits:
71
- - one‑by‑one cherry‑pick with `Change-Id` trailers, or
72
- - squash into a single commit and keep or reuse `Change-Id`.
73
- - Optionally replace the commit message with PR title and body.
74
- - Push with a topic to `refs/for/<branch>` using `git-review` behavior.
75
- - Query Gerrit for the resulting URL, change number, and patchset SHA.
76
- - Add a back‑reference comment in Gerrit to the GitHub PR and run URL.
77
- - Comment on the GitHub PR with the Gerrit change URL(s).
78
- - Optionally close the PR (mirrors the shell action policy).
79
-
80
- ## Requirements
81
-
82
- - Repository contains a `.gitreview` file. If you cannot provide it,
83
- you must pass `GERRIT_SERVER`, `GERRIT_SERVER_PORT`, and
84
- `GERRIT_PROJECT` via the reusable workflow interface.
85
- - SSH key for Gerrit and known hosts are available to the workflow.
86
- - The default `GITHUB_TOKEN` is available for PR metadata and comments.
87
- - The workflow grants permissions required for PR interactions:
88
- - `pull-requests: write` (to comment on and close PRs)
89
- - `issues: write` (to create PR comments via the Issues API)
90
- - The workflow runs with `pull_request_target` or via
91
- `workflow_dispatch` using a valid PR context.
92
-
93
- ### Note on sitecustomize.py
94
-
95
- This repository includes a sitecustomize.py that is automatically
96
- imported by Python’s site initialization. It exists to make pytest and
97
- coverage runs in CI more robust by:
98
-
99
- - assigns a unique COVERAGE_FILE per process to avoid mixing data across runs
100
- - proactively removing stale .coverage artifacts in common base directories.
101
-
102
- The logic runs during pytest sessions and is best effort.
103
- It never interferes with normal execution. Maintainers can keep it to
104
- stabilize coverage reporting for parallel/xdist runs.
105
-
106
- ## Duplicate detection
107
-
108
- Duplicate detection uses a scoring-based approach. Instead of relying on a hash
109
- added by this action, the detector compares the first line of the commit message
110
- (subject/PR title), analyzes the body text and the set of files changed, and
111
- computes a similarity score. When the score meets or exceeds a configurable
112
- threshold (default 0.8), the tool treats the change as a duplicate and blocks
113
- submission. This approach aims to remain robust even when similar changes
114
- appeared outside this pipeline.
115
-
116
- ### Examples of detected duplicates
117
-
118
- - Dependency bumps for the same package across close versions
119
- (e.g., "Bump foo from 1.0 to 1.1" vs "Bump foo from 1.1 to 1.2")
120
- with overlapping files — high score
121
- - Pre-commit autoupdates that change .pre-commit-config.yaml and hook versions —
122
- high score
123
- - GitHub Actions version bumps that update .github/workflows/* uses lines —
124
- medium to high score
125
- - Similar bug fixes with the same subject and significant file overlap —
126
- strong match
127
-
128
- ### Allowing duplicates
129
-
130
- Use `--allow-duplicates` or set `ALLOW_DUPLICATES=true` to override:
131
-
132
- ```bash
133
- # CLI usage
134
- github2gerrit --allow-duplicates https://github.com/org/repo
135
-
136
- # GitHub Actions
137
- uses: onap/github2gerrit@main
138
- with:
139
- ALLOW_DUPLICATES: 'true'
140
- ```
141
-
142
- When allowed, duplicates generate warnings but processing continues.
143
- The tool exits with code 3 when it detects duplicates and they are not allowed.
144
-
145
- ## Usage
146
-
147
- This action runs as part of a workflow that triggers on
148
- `pull_request_target` and also supports manual runs via
149
- `workflow_dispatch`.
150
-
151
- Minimal example:
152
-
153
- ```yaml
154
- name: github2gerrit
155
-
156
- on:
157
- pull_request_target:
158
- types: [opened, reopened, edited, synchronize]
159
- workflow_dispatch:
160
-
161
- permissions:
162
- contents: read
163
- pull-requests: write
164
- issues: write
165
-
166
- jobs:
167
- submit-to-gerrit:
168
- runs-on: ubuntu-latest
169
- steps:
170
- - name: Submit PR to Gerrit
171
- id: g2g
172
- uses: lfit/github2gerrit@main
173
- with:
174
- SUBMIT_SINGLE_COMMITS: "false"
175
- USE_PR_AS_COMMIT: "false"
176
- FETCH_DEPTH: "10"
177
- GERRIT_KNOWN_HOSTS: ${{ vars.GERRIT_KNOWN_HOSTS }}
178
- GERRIT_SSH_PRIVKEY_G2G: ${{ secrets.GERRIT_SSH_PRIVKEY_G2G }}
179
- GERRIT_SSH_USER_G2G: ${{ vars.GERRIT_SSH_USER_G2G }}
180
- GERRIT_SSH_USER_G2G_EMAIL: ${{ vars.GERRIT_SSH_USER_G2G_EMAIL }}
181
- ORGANIZATION: ${{ github.repository_owner }}
182
- REVIEWERS_EMAIL: ""
183
- ISSUE_ID: "" # Optional: adds 'Issue-ID: ...' trailer to the commit message
184
- ```
185
-
186
- The action reads `.gitreview`. If `.gitreview` is absent, you must
187
- supply Gerrit connection details through a reusable workflow or by
188
- setting the corresponding environment variables before invoking the
189
- action. The shell action enforces `.gitreview` for the composite
190
- variant; this Python action mirrors that behavior for compatibility.
191
-
192
- ## Command Line Usage and Debugging
193
-
194
- ### Direct Command Line Usage
195
-
196
- You can run the tool directly from the command line to process GitHub pull requests:
197
-
198
- ```bash
199
- # Process a specific pull request
200
- github2gerrit https://github.com/owner/repo/pull/123
201
-
202
- # Process all open pull requests in a repository
203
- github2gerrit https://github.com/owner/repo
204
-
205
- # Run in CI mode (reads from environment variables)
206
- github2gerrit
207
- ```
208
-
209
- ### Available Options
210
-
211
- ```bash
212
- github2gerrit --help
213
- ```
214
-
215
- Key options include:
216
-
217
- - `--verbose` / `-v`: Enable verbose debug logging
218
- - `--dry-run`: Check configuration without making changes
219
- - `--submit-single-commits`: Submit each commit individually
220
- - `--use-pr-as-commit`: Use PR title/body as commit message
221
- - `--issue-id`: Add an Issue-ID trailer (e.g., "Issue-ID: ABC-123")
222
- to the commit message
223
- - `--preserve-github-prs`: Don't close GitHub PRs after submission
224
-
225
- ### Debugging and Troubleshooting
226
-
227
- When encountering issues, enable verbose logging to see detailed execution:
228
-
229
- ```bash
230
- # Using the CLI flag
231
- github2gerrit --verbose https://github.com/owner/repo/pull/123
232
-
233
- # Using environment variable
234
- G2G_LOG_LEVEL=DEBUG github2gerrit https://github.com/owner/repo/pull/123
235
-
236
- # Alternative environment variable
237
- G2G_VERBOSE=true github2gerrit https://github.com/owner/repo/pull/123
238
- ```
239
-
240
- Debug output includes:
241
-
242
- - Git command execution and output
243
- - SSH connection attempts
244
- - Gerrit API interactions
245
- - Branch resolution logic
246
- - Change-Id processing
247
-
248
- Common issues and solutions:
249
-
250
- 1. **Configuration Validation Errors**: The tool provides clear error messages when
251
- required configuration is missing or invalid. Look for messages starting with
252
- "Configuration validation failed:" that specify missing inputs like
253
- `GERRIT_KNOWN_HOSTS`, `GERRIT_SSH_PRIVKEY_G2G`, etc.
254
- 2. **SSH Permission Denied**: Ensure `GERRIT_SSH_PRIVKEY_G2G` and
255
- `GERRIT_KNOWN_HOSTS` are properly set
256
- 3. **Branch Not Found**: Check that the target branch exists in both GitHub and Gerrit
257
- 4. **Change-Id Issues**: Enable debug logging to see Change-Id generation and validation
258
- 5. **Gerrit API Errors**: Verify Gerrit server connectivity and project permissions
259
-
260
- > **Note**: The tool displays configuration errors cleanly without Python tracebacks.
261
- > If you see a traceback in the output, please report it as a bug.
262
-
263
- ### Environment Variables
264
-
265
- The tool respects these environment variables for configuration:
266
-
267
- - `G2G_LOG_LEVEL`: Set to `DEBUG` for verbose output (default: `INFO`)
268
- - `G2G_VERBOSE`: Set to `true` to enable debug logging
269
- - `GERRIT_SSH_PRIVKEY_G2G`: SSH private key content
270
- - `GERRIT_KNOWN_HOSTS`: SSH known hosts entries
271
- - `GERRIT_SSH_USER_G2G`: Gerrit SSH username
272
- - `DRY_RUN`: Set to `true` for check mode
273
-
274
- ## Advanced usage
275
-
276
- You can explicitly install the SSH key and provide a custom SSH configuration
277
- before invoking this action. This is useful when:
278
-
279
- - You want to override the port/host used by SSH
280
- - You need to define host aliases or SSH options
281
- - Your Gerrit instance uses a non-standard HTTP base path (e.g. /r)
282
-
283
- Example:
284
-
285
- ```yaml
286
- name: github2gerrit (advanced)
287
-
288
- on:
289
- pull_request_target:
290
- types: [opened, reopened, edited, synchronize]
291
- workflow_dispatch:
292
-
293
- permissions:
294
- contents: read
295
- pull-requests: write
296
- issues: write
297
-
298
- jobs:
299
- submit-to-gerrit:
300
- runs-on: ubuntu-latest
301
- steps:
302
-
303
-
304
- - name: Submit PR to Gerrit (with explicit overrides)
305
- id: g2g
306
- uses: lfit/github2gerrit@main
307
- with:
308
- # Behavior
309
- SUBMIT_SINGLE_COMMITS: "false"
310
- USE_PR_AS_COMMIT: "false"
311
- FETCH_DEPTH: "10"
312
-
313
- # Required SSH/identity
314
- GERRIT_KNOWN_HOSTS: ${{ vars.GERRIT_KNOWN_HOSTS }}
315
- GERRIT_SSH_PRIVKEY_G2G: ${{ secrets.GERRIT_SSH_PRIVKEY_G2G }}
316
- GERRIT_SSH_USER_G2G: ${{ vars.GERRIT_SSH_USER_G2G }}
317
- GERRIT_SSH_USER_G2G_EMAIL: ${{ vars.GERRIT_SSH_USER_G2G_EMAIL }}
318
-
319
- # Optional overrides when .gitreview is missing or to force values
320
- GERRIT_SERVER: ${{ vars.GERRIT_SERVER }}
321
- GERRIT_SERVER_PORT: ${{ vars.GERRIT_SERVER_PORT }}
322
- GERRIT_PROJECT: ${{ vars.GERRIT_PROJECT }}
323
-
324
- # Optional Gerrit REST base path and credentials (if required)
325
- # e.g. '/r' for some deployments
326
- GERRIT_HTTP_BASE_PATH: ${{ vars.GERRIT_HTTP_BASE_PATH }}
327
- GERRIT_HTTP_USER: ${{ vars.GERRIT_HTTP_USER }}
328
- GERRIT_HTTP_PASSWORD: ${{ secrets.GERRIT_HTTP_PASSWORD }}
329
-
330
- ORGANIZATION: ${{ github.repository_owner }}
331
- REVIEWERS_EMAIL: ""
332
- ```
333
-
334
- Notes:
335
-
336
- - The action configures SSH internally using the provided inputs (key,
337
- known_hosts) and does not use the runner’s SSH agent or ~/.ssh/config.
338
- - Do not add external steps to install SSH keys or edit SSH config; they’re
339
- unnecessary and may conflict with the action.
340
-
341
- ## GitHub Enterprise support
342
-
343
- - Direct-URL mode accepts enterprise GitHub hosts when explicitly enabled.
344
- Default: off (use github.com by default). Enable via the CLI flag
345
- --allow-ghe-urls or by setting ALLOW_GHE_URLS="true".
346
- - In GitHub Actions, this action works with GitHub Enterprise when the
347
- workflow runs in that enterprise environment and provides a valid
348
- GITHUB_TOKEN. For direct-URL runs outside Actions, ensure ORGANIZATION
349
- and GITHUB_REPOSITORY reflect the target repository.
350
-
351
- ## Inputs
352
-
353
- All inputs are strings, matching the composite action.
354
-
355
- - SUBMIT_SINGLE_COMMITS
356
- - Submit one commit at a time to Gerrit. Default: "false".
357
- - USE_PR_AS_COMMIT
358
- - Use PR title and body as the commit message. Default: "false".
359
- - FETCH_DEPTH
360
- - Depth used when checking out the repository. Default: "10".
361
- - GERRIT_KNOWN_HOSTS
362
- - SSH known hosts content for the Gerrit host. Required.
363
- - GERRIT_SSH_PRIVKEY_G2G
364
- - SSH private key for Gerrit. Required.
365
- - GERRIT_SSH_USER_G2G
366
- - Gerrit SSH username. Required.
367
- - GERRIT_SSH_USER_G2G_EMAIL
368
- - Gerrit SSH user email (used for commit identity). Required.
369
- - ORGANIZATION
370
- - Organization name, defaults to `github.repository_owner`.
371
- - REVIEWERS_EMAIL
372
- - Comma separated reviewer emails. If empty, defaults to
373
- `GERRIT_SSH_USER_G2G_EMAIL`.
374
- - ALLOW_GHE_URLS
375
- - Allow non-github.com GitHub Enterprise URLs in direct URL mode. Default: "false".
376
- - Set to "true" to allow non-github.com enterprise hosts.
377
-
378
- Optional inputs when `.gitreview` is not present (parity with
379
- the reusable workflow):
380
-
381
- - GERRIT_SERVER
382
- - Gerrit host, e.g. `git.opendaylight.org`. Default: "".
383
- - GERRIT_SERVER_PORT
384
- - Gerrit port, default "29418".
385
- - GERRIT_PROJECT
386
- - Gerrit project name, e.g. `releng/builder`. Default: "".
387
-
388
- ## Outputs
389
-
390
- - url
391
- - Gerrit change URL(s). Multi‑line when the action submits more than one change.
392
- - change_number
393
- - Gerrit change number(s). Multi‑line when the action submits more than one change.
394
-
395
- These outputs mirror the composite action. They are also exported into
396
- the environment as:
397
-
398
- - GERRIT_CHANGE_REQUEST_URL
399
- - GERRIT_CHANGE_REQUEST_NUM
400
-
401
- ## Known Keys
402
-
403
- The table below lists all the configuration directives supported by the tool,
404
- along with the corresponding environment variable (also GitHub action input)
405
- and the corresponding CLI flags.
406
-
407
- <!-- markdownlint-disable MD013 -->
408
-
409
- | Environment Variable / GitHub Input | Configuration Directive | CLI Flag | Description |
410
- |-------------------------------------|-------------------------|----------|-------------|
411
- | `SUBMIT_SINGLE_COMMITS` | `submit_single_commits` | `--submit-single-commits` | Submit one commit at a time to the Gerrit repository |
412
- | `USE_PR_AS_COMMIT` | `use_pr_as_commit` | `--use-pr-as-commit` | Use PR title and body as the commit message |
413
- | `FETCH_DEPTH` | `fetch_depth` | `--fetch-depth` | Fetch-depth for the clone (default: 10) |
414
- | `GERRIT_KNOWN_HOSTS` | `gerrit_known_hosts` | `--gerrit-known-hosts` | Known hosts entries for Gerrit SSH |
415
- | `GERRIT_SSH_PRIVKEY_G2G` | `gerrit_ssh_privkey_g2g` | `--gerrit-ssh-privkey-g2g` | SSH private key for Gerrit (string content) |
416
- | `GERRIT_SSH_USER_G2G` | `gerrit_ssh_user_g2g` | `--gerrit-ssh-user-g2g` | Gerrit SSH user |
417
- | `GERRIT_SSH_USER_G2G_EMAIL` | `gerrit_ssh_user_g2g_email` | `--gerrit-ssh-user-g2g-email` | Email address for the Gerrit SSH user |
418
- | `ORGANIZATION` | `organization` | `--organization` | Organization (defaults to GITHUB_REPOSITORY_OWNER when unset) |
419
- | `REVIEWERS_EMAIL` | `reviewers_email` | `--reviewers-email` | Comma-separated list of reviewer emails |
420
- | `ALLOW_GHE_URLS` | `allow_ghe_urls` | `--allow-ghe-urls` | Allow non-github.com GitHub Enterprise URLs in direct URL mode |
421
- | `PRESERVE_GITHUB_PRS` | `preserve_github_prs` | `--preserve-github-prs` | Do not close GitHub PRs after pushing to Gerrit |
422
- | `DRY_RUN` | `dry_run` | `--dry-run` | Check settings and PR metadata; do not write to Gerrit |
423
- | `GERRIT_SERVER` | `gerrit_server` | `--gerrit-server` | Gerrit server hostname (optional; .gitreview preferred) |
424
- | `GERRIT_SERVER_PORT` | `gerrit_server_port` | `--gerrit-server-port` | Gerrit SSH port (default: 29418) |
425
- | `GERRIT_PROJECT` | `gerrit_project` | `--gerrit-project` | Gerrit project (optional; .gitreview preferred) |
426
- | `ISSUE_ID` | `issue_id` | `--issue-id` | Issue ID to include in commit message (e.g., Issue-ID: ABC-123) |
427
- | `ALLOW_DUPLICATES` | `allow_duplicates` | `--allow-duplicates` | Allow submitting duplicate changes without error |
428
- | `G2G_VERBOSE` | `g2g_verbose` | `--verbose` / `-v` | Enable verbose debug logging |
429
- | `G2G_SKIP_GERRIT_COMMENTS` | `g2g_skip_gerrit_comments` | N/A | Skip adding back-reference comments to Gerrit changes |
430
- | `GITHUB_TOKEN` | `github_token` | N/A | GitHub API token for accessing repository and PR data |
431
- | `PR_NUMBER` | `pr_number` | N/A | Pull request number (set automatically in CI) |
432
- | `SYNC_ALL_OPEN_PRS` | `sync_all_open_prs` | N/A | Process all open pull requests (internal use) |
433
- | `GERRIT_HTTP_BASE_PATH` | `gerrit_http_base_path` | N/A | HTTP base path for Gerrit API (e.g., "/r") |
434
- | `GERRIT_HTTP_USER` | `gerrit_http_user` | N/A | Gerrit HTTP username for REST API authentication |
435
- | `GERRIT_HTTP_PASSWORD` | `gerrit_http_password` | N/A | Gerrit HTTP password/token for REST API authentication |
436
-
437
- <!-- markdownlint-enable MD013 -->
438
-
439
- ### Configuration Precedence
440
-
441
- The tool follows this precedence order for configuration values:
442
-
443
- 1. **CLI flags** (highest priority)
444
- 2. **Environment variables**
445
- 3. **Configuration file values**
446
- 4. **Tool defaults** (lowest priority)
447
-
448
- ### Configuration File Format
449
-
450
- Configuration files use INI format with organization-specific sections:
451
-
452
- ```ini
453
- [default]
454
- GERRIT_SERVER = "gerrit.example.org"
455
- PRESERVE_GITHUB_PRS = "true"
456
-
457
- [onap]
458
- ISSUE_ID = "CIMAN-33"
459
- REVIEWERS_EMAIL = "user@example.org"
460
-
461
- [opendaylight]
462
- GERRIT_HTTP_USER = "bot-user"
463
- GERRIT_HTTP_PASSWORD = "${ENV:ODL_GERRIT_TOKEN}"
464
- ```
465
-
466
- The tool loads configuration from `~/.config/github2gerrit/configuration.txt`
467
- by default, or from the path specified in the `G2G_CONFIG_PATH` environment
468
- variable.
469
-
470
- **Note**: Unknown configuration keys will generate warnings to help catch typos
471
- and missing functionality.
472
-
473
- ## Behavior details
474
-
475
- - Branch resolution
476
- - Uses `GITHUB_BASE_REF` as the target branch for Gerrit, or defaults
477
- to `master` when unset, matching the existing workflow.
478
- - Topic naming
479
- - Uses `GH-<repo>-<pr-number>` where `<repo>` replaces slashes with
480
- hyphens.
481
- - GitHub Enterprise support
482
- - Direct URL mode accepts enterprise GitHub hosts when explicitly enabled
483
- (default: off; use github.com by default). Enable via --allow-ghe-urls or
484
- ALLOW_GHE_URLS="true". The tool determines the GitHub API base URL from
485
- GITHUB_API_URL or GITHUB_SERVER_URL/api/v3.
486
- - Change‑Id handling
487
- - Single commits: the process amends each cherry‑picked commit to include a
488
- `Change-Id`. The tool collects these values for querying.
489
- - Squashed: collects trailers from original commits, preserves
490
- `Signed-off-by`, and reuses the `Change-Id` when PRs reopen or synchronize.
491
- - Reviewers
492
- - If empty, defaults to the Gerrit SSH user email.
493
- - Comments
494
- - Adds a back‑reference comment in Gerrit with the GitHub PR and run
495
- URL. Adds a comment on the GitHub PR with the Gerrit change URL(s).
496
- - Closing PRs
497
- - On `pull_request_target`, the workflow may close the PR after submission to
498
- match the shell action’s behavior.
499
-
500
- ## Security notes
501
-
502
- - Do not hardcode secrets or keys. Provide the private key via the
503
- workflow secrets and known hosts via repository or org variables.
504
- - SSH handling is non-invasive: the tool creates temporary SSH files in
505
- the workspace without modifying user SSH configuration or keys.
506
- - SSH agent scanning prevention uses `IdentitiesOnly=yes` to avoid
507
- unintended key usage (e.g., signing keys requiring biometric auth).
508
- - Temporary SSH files are automatically cleaned up after execution.
509
- - All external calls should use retries and clear error reporting.
510
-
511
- ## Development
512
-
513
- This repository follows the guidelines in `CLAUDE.md`.
514
-
515
- - Language and CLI
516
- - Python 3.11. The CLI uses Typer.
517
- - Packaging
518
- - `pyproject.toml` with setuptools backend. Use `uv` to install and run.
519
- - Structure
520
- - `src/github2gerrit/cli.py` (CLI entrypoint)
521
- - `src/github2gerrit/core.py` (orchestration)
522
- - `src/github2gerrit/gitutils.py` (subprocess and git helpers)
523
- - Linting and type checking
524
- - Ruff and MyPy use settings in `pyproject.toml`.
525
- - Run from pre‑commit hooks and CI.
526
- - Tests
527
- - Pytest with coverage targets around 80%.
528
- - Add unit and integration tests for each feature.
529
-
530
- ### Local setup
531
-
532
- - Install `uv` and run:
533
- - `uv pip install --system .`
534
- - `uv run github2gerrit --help`
535
- - Run tests:
536
- - `uv run pytest -q`
537
- - Lint and type check:
538
- - `uv run ruff check .`
539
- - `uv run black --check .`
540
- - `uv run mypy src`
541
-
542
- ### Notes on parity
543
-
544
- - Inputs, outputs, and environment usage match the shell action.
545
- - The action assumes the same GitHub variables and secrets are present.
546
- - Where the shell action uses tools such as `jq` and `gh`, the Python
547
- version uses library calls and subprocess as appropriate, with retries
548
- and clear logging.
549
-
550
- ## License
551
-
552
- Apache License 2.0. See `LICENSE` for details.
@@ -1,17 +0,0 @@
1
- github2gerrit/__init__.py,sha256=N1Vj1HJ28LKCJLAynQdm5jFGQQAz9YSMzZhEfvbBgow,886
2
- github2gerrit/cli.py,sha256=86Xvjk9xsSN76ewXjBbA0yWIncnkyIy3VFb2pUN7HAM,34637
3
- github2gerrit/config.py,sha256=sTiujlOjCsJbaA-Ftr5XR--9nxs7XH8uEWD-IbGqLYk,17370
4
- github2gerrit/core.py,sha256=Tg1Qxg7tvGCxAfC0cSFnkexeN2JVIVkv0zqvov1S-RY,79296
5
- github2gerrit/duplicate_detection.py,sha256=ODPzCm6Gv5NZsxkPm1vy4CBsWQ7hIhD7U95TiXWwcts,29986
6
- github2gerrit/gerrit_urls.py,sha256=A-bi6JbicnqR5WAg-cLpWzDQczkWMoahCVqNl21wARo,8395
7
- github2gerrit/github_api.py,sha256=nteSZjMiFP64pUJc9tqtvUgiaGlKtaH62zJWfGbR19I,10528
8
- github2gerrit/gitutils.py,sha256=4-UXLX3L_nUJbXbcYx1FvpikUdsr5BwnnlI-GwbeXu0,19410
9
- github2gerrit/models.py,sha256=-iBFJXyWEW1mFNn_wkkHjMenxoKB5SNNzJHhZ2IkxFA,1827
10
- github2gerrit/similarity.py,sha256=gcz9wSK6xZjff0MD_VNHLpxJUWH7Z0ZAYT25t46qpgY,15228
11
- github2gerrit/ssh_discovery.py,sha256=XSV01p2nMMKBbTWAAmrWr-VMDdBZMxcMt5Nu04pDdH4,12825
12
- github2gerrit-0.1.6.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
13
- github2gerrit-0.1.6.dist-info/METADATA,sha256=QNKgaz_XAC42GVQuNaHoZYTOia2ncvlDaOHatXaarsY,21471
14
- github2gerrit-0.1.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
15
- github2gerrit-0.1.6.dist-info/entry_points.txt,sha256=MxN2_liIKo3-xJwtAulAeS5GcOS6JS96nvwOQIkP3W8,56
16
- github2gerrit-0.1.6.dist-info/top_level.txt,sha256=bWTYXjvuu4sSU90KLT1JlnjD7xV_iXZ-vKoulpjLTy8,14
17
- github2gerrit-0.1.6.dist-info/RECORD,,