gerrit-to-platform 0.4.0

Private and Restricted Changes

Before dispatching for patchset-created and comment-added events, gerrit-to-platform probes the change anonymously over the Gerrit REST API (GET <base>/changes/<number>). Gerrit answers HTTP 404 for changes the requester cannot see — private changes in particular — which matches what the platform-side service account and the replication mirror can access. When the change is unreadable the dispatch is skipped and the reason is logged; Gerrit fires a fresh event when the change is published, so no verification coverage is lost.

The probe fails open: network errors, timeouts and unexpected statuses all allow the dispatch to proceed, so a Gerrit REST outage can never block CI. change-merged events skip the probe because Gerrit refuses to submit private changes.

On Gerrit servers without anonymous REST read access every change would probe as HTTP 404, so operators of such servers must disable the gate with visibility_check = false in the [gerrit] section (see above).

GitHub Workflow Configuration

There are three hooks that gerrit-to-platform handles:

• patchset-created (search filter: verify)

• change-merged (search filter: merge)

• comment-added (comment mapping for keyword to search filter)

Configuration for triggered workflows must meet the following requirements:

• The workflow filename must contain ‘gerrit’

• The workflow filename must contain the search filter

Required workflows (those that should run on all projects) must be part of the ORGANIZATION/.github magic repository. These workflow filenames must also contain ‘required’.

ex: .github/workflows/gerrit-required-verify.yaml

You can put standard workflows (non-required ones) into a project’s repository, in the .github directory. These should have filenames that include ‘gerrit’ and the search filter, as discussed above, but do not need anything beyond. They should never include ‘required’ in their filename.

ex: .github/workflows/gerrit-merge.yaml or .github/workflows/gerrit-sonar-novote-verify.yaml

Filename matching is a case-insensitive substring test (str.find), not a prefix or exact match: a workflow is selected when its filename contains both gerrit and the search filter anywhere in the name. The recommended naming convention is gerrit-<description>-<event>.yaml so that the gerrit- prefix opts the workflow into Gerrit dispatch and the trailing event keyword (verify, merge, or a custom comment keyword) selects the hook.

ex: gerrit-verify.yaml, gerrit-maven-merge.yaml, gerrit-release-merge.yaml

Because the match is a substring and gerrit-to-platform dispatches every matching workflow for an event, two cautions apply:

• Choose names so that only the intended workflows match. For example, both gerrit-maven-merge.yaml and gerrit-release-merge.yaml contain merge and therefore both fire on every change-merged event.

• A workflow that must not act on every event has to self-gate, for example by inspecting the changed files or GERRIT_EVENT_TYPE and exiting early when it does not apply.

For comment-added triggers the search filter is the value mapped to the keyword in the [mapping "comment-added"] section described above, so the workflow filename must contain that mapped filter. For example, with stage-release = stage a posted stage-release comment selects workflows whose filename contains both gerrit and stage, such as gerrit-maven-stage.yaml.

All workflows must have the following primary configuration:

---
name: Gerrit Verify

# yamllint disable-line rule:truthy
on:
  workflow_dispatch:
    inputs:
      GERRIT_BRANCH:
        description: 'Branch that change is against'
        required: true
        type: string
      GERRIT_CHANGE_ID:
        description: 'The ID for the change'
        required: true
        type: string
      GERRIT_CHANGE_NUMBER:
        description: 'The Gerrit number'
        required: true
        type: string
      GERRIT_CHANGE_URL:
        description: 'URL to the change'
        required: true
        type: string
      GERRIT_EVENT_TYPE:
        description: 'Gerrit event type'
        required: true
        type: string
      GERRIT_PATCHSET_NUMBER:
        description: 'The patch number for the change'
        required: true
        type: string
      GERRIT_PATCHSET_REVISION:
        description: 'The revision sha'
        required: true
        type: string
      GERRIT_PROJECT:
        description: 'Project in Gerrit'
        required: true
        type: string
      GERRIT_REFSPEC:
        description: 'Gerrit refspec of change'
        required: true
        type: string


concurrency:
  group: ${{ github.event.inputs.GERRIT_CHANGE_ID || github.run_id }}
  cancel-in-progress: true

jobs:
  <your_job_configurations>

Required workflows must have the following extra input:

TARGET_REPO:
  description: 'The target GitHub repository needing the required workflow'
  required: true
  type: string

ChatOps Workflow

Trigger GitHub Actions workflows directly from Gerrit by adding comments to your changes. This eliminates the need for manual workflow triggers and enables automated testing on-demand.

To trigger a workflow, add a comment to any Gerrit change using the pattern:

gha-<action> <workflow-name> <parameters>

For example:

gha-run csit-2n-perftest nic=intel-e810cq drv=avf

Common examples include:

gha-run csit-2n-perftest nic=intel-e810cq drv=avf
gha-run csit-3n-perftest mrrANDnic_intel-e810cqANDdrv_avfAND4c
gha-run csit-2n-mrr-weekly
gha-run csit-3n-mrr-daily nic=intel-x710
gha-run terraform-cdash-deploy env=production
gha-run terraform-infra-update region=us-west
gha-run vpp-build type=release arch=x86_64
gha-run vpp-verify compiler=gcc
gha-run hicn-verify arch=amd64
gha-run cicn-build type=debug
gha-run hc2vpp-integration-test
gha-run hc2vpp-verify

Specify parameters in two formats:

1. Key=Value format (recommended):

   gha-run csit-2n-perftest nic=intel-e810cq drv=avf framesize=64

2. AND-separated format (legacy support):

   gha-run csit-2n-perftest mrrANDnic_intel-e810cqANDdrv_avfAND4c

Cooldown Period: To prevent workflow spam, there is a 5-minute cooldown between commands for the same workflow on the same change. If you trigger a workflow and need to run it again, wait 5 minutes before commenting.

Troubleshooting: If your command doesn’t trigger a workflow:

• Verify the command starts with gha- followed by the action and workflow name

• Check that the workflow name matches a supported pattern for your project

• Wait 5 minutes if you triggered the same workflow on this change within the last 5 minutes

• Review GitHub Actions logs for error messages

Workflow Configuration: Name workflows that respond to ChatOps commands comment-handler and include a GERRIT_COMMENT input that receives the full command line. The workflow then parses the command to determine which handler to execute. See gerrit-comment-handler.yaml for a complete example.

Workflow Migration Guide

This section helps teams migrate from vanilla GitHub workflows (or Jenkins jobs) to Gerrit-integrated GitHub Actions workflows. The examples/workflows/ directory contains annotated example workflows.

concurrency:
  group: ${{ github.event.inputs.GERRIT_CHANGE_ID || github.run_id }}
  cancel-in-progress: true

Making Changes & Contributing

This project uses pre-commit, please make sure to install it before making any changes:

pip install pre-commit
cd gerrit_to_platform
pre-commit install
pre-commit install -t commit-msg

Don’t forget to tell your contributors to also install and use pre-commit.

Note

PyScaffold 4.4 provided the initial project setup. For details and usage information on PyScaffold see https://pyscaffold.org/.