gerrit_to_platform package

Submodules

gerrit_to_platform.change_merged module

Handler for change-merged events.

gerrit_to_platform.change_merged.change_merged(change: str, change_url: str, change_owner: str, change_owner_username: str, project: str, branch: str, topic: str, submitter: str, submitter_username: str, commit: str, newrev: str)

Handle change-merged hook.

Parameters:

• change (str) – change ID

• change_url (str) – change URL

• change_owner (str) – change owner eg: ‘Foo <foo@example.com>’

• change_owner_username (str) – change owner username eg: ‘foo’

• project (str) – Gerrit project name

• branch (str) – branch change is against

• topic (str) – topic change is part of

• submitter (str) – submitter of change eg: ‘Foo <foo@example.com>’

• submitter_username (str) – submitter of change username eg: ‘foo’

• commit (str) – SHA1 of commit

• newrev (str) – SHA1 of commit

gerrit_to_platform.comment_added module

Handler for comment-added events.

gerrit_to_platform.comment_added.check_cooldown(change_number: str, workflow_name: str) → bool

Check if workflow trigger is within cooldown period.

Parameters:

• change_number – Gerrit change number

• workflow_name – Name of the workflow to trigger

Returns:

True if trigger is allowed, False if still in cooldown

Return type:

bool

gerrit_to_platform.comment_added.comment_added(context: Context, change: str, change_url: str, change_owner: str, change_owner_username: str, project: str, branch: str, topic: str, author: str, author_username: str, commit: str, comment: str)

Handle comment-added hook.

Supports two trigger mechanisms: 1. gha-<action> <workflow_name> pattern for direct workflow triggering

Example: “gha-run csit-2n-perftest nic=intel-e810cq drv=avf” The full command line is passed to the workflow via GERRIT_COMMENT input for parameter parsing by the GitHub Actions workflow.

2. Keyword mapping from config file (legacy behavior)

Approval scores should be added as –<approval category id> <score>

When a score is removed it should be –<approval category id>-oldValue <score>

Multiple scores and old scores may be passed

ex: –Code-Review +1 –Code-Review-oldValue 0

Parameters:

• context (typer.Context) – handler for the typer context to allow for extra non-defined parameters (code scores, see above)

• change (str) – change ID

• change_url (str) – change URL

• change_owner (str) – change owner eg: ‘Foo <foo@example.com>’

• change_owner_username (str) – change owner username eg: ‘foo’

• project (str) – Gerrit project name

• branch (str) – branch change is against

• topic (str) – topic change is part of

• submitter (str) – submitter of change eg: ‘Foo <foo@example.com>’

• submitter_username (str) – submitter of change username eg: ‘foo’

• commit (str) – SHA1 of commit

• comment (str) – the comment added to the change

gerrit_to_platform.config module

Configuration subsystem.

class gerrit_to_platform.config.Platform(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enumeration of all platforms recognized by the app.

GITHUB = 'github'

GITLAB = 'gitlab'

class gerrit_to_platform.config.Remote

Bases: TypedDict

Remote Dictionary definition.

owner: str

remotenamestyle: str

repo: str

class gerrit_to_platform.config.ReplicationRemotes

Bases: TypedDict

Platform Dictionary definition.

github: Dict[str, Remote]

gitlab: Dict[str, Remote]

gerrit_to_platform.config.get_config(config_type: str = 'config') → ConfigParser

Get the config object.

Parameters:

config_type (str) – Type of configuration file that the parser should use

Returns:

A loaded ConfigParser object with the requested

configuration file

Return type:

ConfigParser

Notes

replication.config follows git’s config-file syntax, which permits the same option key to repeat inside a section (the canonical example is multiple fetch = ... refspecs under one [remote "..."]). Python’s configparser raises DuplicateOptionError for that pattern unless strict is false, so we disable the strict check here. g2p only reads url, authgroup and remotenamestyle from the remote sections, never the multi-valued fetch key, so the “last value wins” semantics that strict=False introduces for duplicates have no functional impact. The same parser is used for gerrit_to_platform.ini for consistency; that file is operator-controlled and does not contain duplicate keys in practice.

gerrit_to_platform.config.get_mapping(mapping_section: str) → Dict[str, str] | None

Return all of the keyword to job mappings

Parameters:

mapping_section (str) – the section of the config file to load

Returns:

The key / value mapping object or None if it

does not exist

Return type:

Optional(Dict[str,str])

gerrit_to_platform.config.get_replication_remotes() → ReplicationRemotes

Get the replication remotes available.

Returns:

All the replication remotes defined the Gerrit

configuration file

Return type:

ReplicationRemotes

gerrit_to_platform.config.get_setting(section: str, option: str | None = None) → list | str

Get all configuration options from a section, or specific option from a section.

Parameters:

• section (str) – config section to use

• option (Optional[str]) – a suboption to get from the section

Returns:

all of the configuration for a section str: the single sub-option of a section

Return type:

list

gerrit_to_platform.config.has_section(section: str) → bool

Indicate if section exists in config file.

Parameters:

section (str) – config section to lookup

Returns:

True if the section exists in configuration, False otherwise

Return type:

bool

gerrit_to_platform.gerrit module

Gerrit REST helpers for change visibility checks.

The hooks this package handles run server-side with full visibility of every change, including private ones. The platform-side service account does not share that visibility: private change refs are not replicated to the mirrors, so any workflow dispatched for a private change fails immediately (see issue #116).

The Gerrit hooks plugin does not pass --private/--wip flags to the patchset-created hook, so the private state cannot be read from the hook payload. Instead, this module probes the change anonymously over the Gerrit REST API. Gerrit answers HTTP 404 for changes the requester cannot see, which is exactly the condition that matters: a change invisible to anonymous users is also invisible to the platform-side account and its refs are absent from the mirror.

The probe fails open: any outcome other than a definitive 404 (network error, timeout, unexpected status, unparseable change URL) allows the dispatch to proceed, so a Gerrit REST outage can never block CI.

gerrit_to_platform.gerrit.get_rest_base_url(change_url: str) → str | None

Derive the Gerrit REST base URL from a change URL.

Parameters:

change_url (str) – the change URL passed by the Gerrit hook, e.g. https://gerrit.example.org/r/c/project/+/12345

Returns:

the base URL (e.g.

https://gerrit.example.org/r) or None when the URL does not match the expected shape.

Return type:

Optional[str]

gerrit_to_platform.gerrit.is_change_readable(change_url: str, change_number: str) → bool

Best-effort probe of whether a change is readable platform-side.

Performs an anonymous GET <base>/changes/<number> against the Gerrit server named in the change URL. Gerrit responds 404 for changes the requester cannot see (private changes in particular), which mirrors what the platform-side service account and the replication mirror can access.

The check fails open: only a definitive HTTP 404 reports the change as unreadable. Network errors, timeouts, unexpected statuses and malformed URLs all return True so that dispatching continues as before this check existed.

Parameters:

• change_url (str) – the change URL passed by the Gerrit hook

• change_number (str) – the change number extracted from the URL

Returns:

False when Gerrit definitively reports the change as not

visible, True otherwise.

Return type:

bool

gerrit_to_platform.gerrit.is_visibility_check_enabled() → bool

Indicate whether the change visibility gate is enabled.

The gate is on by default. Operators of Gerrit servers that do not allow anonymous REST read access (where every change would probe as 404 and dispatching would stop entirely) can disable it in gerrit_to_platform.ini:

[gerrit]
visibility_check = false

Returns:

False only when the option is explicitly set to a falsy

value (false, no, off or 0), True otherwise.

Return type:

bool

gerrit_to_platform.github module

Github connection module.

gerrit_to_platform.github.dispatch_workflow(owner: str, repository: str, workflow_id: str, ref: str, inputs: Dict[str, str]) → Any

Trigger target workflow on GitHub.

Parameters:

• owner (str) – GitHub owner (user or organization)

• repository (str) – target repository

• workflow_id (str) – ID of the workflow to trigger

• ref (str) – the commit ref to trigger with

• inputs (Dict[str, str]) – dictionary of key / value pairs to pass as inputs to the workflow

gerrit_to_platform.github.filter_path(search_filter: str, workflow: Dict[str, str]) → bool

Case insensitive path filter for use in lambda filters.

Parameters:

• search_filter (str) – string to search workflow file names for

• workflow (Dict[str, str]) – dictionary containing all data related to the workflow being evaluated

Returns:

True if search_filter matches in workflow[“path”], False otherwise

Return type:

bool

gerrit_to_platform.github.filter_workflows(owner: str, repository: str, search_filter: str, search_required: bool = False) → List[Dict[str, str]]

Return a case insensitive filtered list of workflows.

All workflows must meet the basic filtering of containing the search_filter in the name as well as “gerrit” in the name.

If search_required is true, then the list will contiain all workflows that contain “required” in the name

If search_required is false (the default), then the list will _exclude_ all workflows that contain “required” in the name.

Parameters:

• owner (str) – GitHub owner (entity or organization)

• repository (str) – target repository

• search_filter (str) – the substring to search for in workflow filenames

• search_required (bool) – if workflows with “required” in the filename are to be returned. If false, then required workflows will be filtered out, if true only required workflows will be returned.

Returns:

list of dictionaries containing all workflows

that meet the search criteria of having “gerrit” in the name, the search_filter substring, and either required or not required according to the search_required argument.

Return type:

List[Dict[str, str]]

gerrit_to_platform.github.get_workflows(owner: str, repository: str) → List[Dict[str, str]]

Get all active workflows for specific repository.

Parameters:

• owner (str) – GitHub owner (entity or organization)

• repository (str) – target repository

Returns:

list of dictionaries containing data related to

active workflows in the target repository.

Return type:

List[Dict[str, str]]

gerrit_to_platform.helpers module

Common helper functions.

gerrit_to_platform.helpers.choose_dispatch(platform: Platform) → Callable | None

Choose platform job dispatcher.

Parameters:

platform (Platform) – the platform that the dispatch is being looked up for

Returns:

The appropriate callable matching the dispatch_worfklow call

signature for the platform

None: If no dispatch_workflow is defined for the platform passed in a

None is returned

Return type:

Callable

gerrit_to_platform.helpers.choose_filter_workflows(platform: Platform) → Callable | None

Choose platform workflow filter.

Parameters:

platform (Platform) – the platform that the filter_workflows is being looked up for

Returns:

The appropriate callable matching the filter_workflows call

signature for the platform

None: If no filter_workflows is defined for the platform passed in a

None is returned

Return type:

Callable

gerrit_to_platform.helpers.convert_repo_name(remotes: ReplicationRemotes, platform: Platform, remote: str, repository: str) → str

Convert the repository name based on the remotenamestyle of the target platform/owner.

Parameters:

• remotes (ReplicationRemotes) – object containing the defined remotes styles

• platform (Platform) – what platform is the conversion happening against

• remote (str) – The specific remote that is being worked on

• repository (str) – The repository name that needs conversion

Returns:

The repository name converted to the appropriate flattening for

the target remote

Return type:

str

gerrit_to_platform.helpers.find_and_dispatch(project: str, workflow_filter: str, inputs: Dict[str, str]) → int

Find relevant workflows and dispatch them.

Parameters:

• project (str) – the project repository name

• workflow_filter (str) – the filter for the workflow names

• inputs (Dict[str, str]) – key / value pair dictionary for inputs to be passed to the target workflow dispatch

Returns:

The number of workflows dispatched

Return type:

int

gerrit_to_platform.helpers.get_change_id(change: str) → str

Return a Gerrit change identifier from the hook --change value.

Gerrit hooks pass --change in one of two shapes depending on the server version and configuration:

• Legacy triplet (e.g. project~branch~Iabc123def...). The third tilde-separated field is the commit-message Change-Id footer. When this shape is detected the function returns that I... value, preserving the previous behaviour.

• Modern compact (Gerrit 3.x and later, e.g. ccsdk%2Fapps~1 — URL-encoded project followed by the change number). Gerrit no longer ships the commit-message Change-Id footer in the hook argv for this shape, so the function returns the compact id as-is. It is still a unique, stable identifier per change and works as a GERRIT_CHANGE_ID workflow input (e.g. for concurrency keys).

Parameters:

change (str) – the --change value supplied by the Gerrit hook plugin.

Returns:

The legacy I... Change-Id when present, otherwise the modern compact project~number identifier verbatim.

Return type:

str

Raises:

ValueError – if change matches neither shape. The previous implementation raised IndexError here, which made triage harder for operators inspecting hook tracebacks.

gerrit_to_platform.helpers.get_change_number(change_url: str) → str

Get the Gerrit change_number

Parameters:

change_url (str) – the url to the specific change passed by the Gerrit event

Returns:

The change number as string extracted from the url

Return type:

str

gerrit_to_platform.helpers.get_change_refspec(change_number: str, patchset: str) → str

Return the change refspec from the change number (str) and patch number

Parameters:

• change_number (str) – The change number to work with

• patchset (str) – The patchset number to work with

Returns:

The git refspec pointing to the hidden ref for the specific change

and patchset

Return type:

str

gerrit_to_platform.helpers.get_magic_repo(platform: Platform) → str | None

Get the “magic” repo for a given Platform used to store organization wide required workflows

Parameters:

platform (Platform) – Platform to lookup magic repo for

Returns:

The magic repo name or None if not defined for the

platform

Return type:

Optional[str]

gerrit_to_platform.patchset_created module

Handler for patchset-created events.

gerrit_to_platform.patchset_created.patchset_created(change: str, kind: str, change_url: str, change_owner: str, change_owner_username: str, project: str, branch: str, topic: str, uploader: str, uploader_username: str, commit: str, patchset: str)

Handle patcheset-created hook.

Parameters:

• change (str) – change ID

• kind (str) – type of change

• change_url (str) – change URL

• change_owner (str) – change owner eg: ‘Foo <foo@example.com>’

• change_owner_username (str) – change owner username eg: ‘foo’

• project (str) – Gerrit project name

• branch (str) – branch change is against

• topic (str) – topic change is part of

• uploader (str) – uploader of change eg: ‘Foo <foo@example.com>’

• uploader_username (str) – uploader of change username eg: ‘foo’

• commit (str) – SHA1 of commit

• patchset (str) – patchset number

Module contents