lfreleng-actions/⚙️ Gerrit Server Container
Starts Gerrit server(s) with pull-replication plugin for mirroring production Gerrit instances
View on GitHubTrust Signals
- Scorecard Score
- not yet scored
- Maintenance Recency
- Activelast commit Jul 8, 2026
- License
- None
Pinned Snippet
uses: lfreleng-actions/gerrit-action@4e72383922d865b25b8eca292f686dcef3bce2d7 # v0.3.1tags can be moved; commit SHAs can't. why a SHA?
Inputs
| name | description | required | default |
|---|---|---|---|
| gerrit_setup | JSON array defining Gerrit instances to start. Format: [{"slug": "onap", "gerrit": "gerrit.onap.org", "project": "", "api_path": "/r"}] Fields: - slug (required): Short identifier for the instance - gerrit (required): Gerrit server hostname - project (optional): Project filter for replication - Empty string or omitted: Replicate ALL projects from server - Literal name: "releng/lftools" - single project - Comma-separated: "releng/lftools,ci-management" - multiple projects - Regex pattern: "regex:releng/.*" or "regex:^infra/.*" - pattern matching - api_path (optional): API path prefix (e.g., "/infra", "/r", "/gerrit") Can be overridden by repository variable GERRIT_SETUP | yes | — |
| ssh_private_key | SSH private key for Gerrit sync authentication | no | — |
| ssh_known_hosts | SSH known_hosts entries for Gerrit servers (auto-generated if not provided) | no | — |
| http_username | HTTP basic auth username (required if auth_type=http_basic) | no | — |
| http_password | HTTP basic auth password (required if auth_type=http_basic) | no | — |
| bearer_token | Bearer token for HTTP authentication (required if auth_type=bearer_token) | no | — |
| gerrit_version | Gerrit Docker image version tag | no | 3.13.1-ubuntu24 |
| plugin_version | Pull-replication plugin version/branch | no | stable-3.13 |
| base_http_port | Starting HTTP port (increments for multi-instance) | no | 8080 |
| base_ssh_port | Starting SSH port (increments for multi-instance) | no | 29418 |
| auth_type | Authentication method: ssh, http_basic, or bearer_token | no | ssh |
| remote_ssh_user | SSH username for authenticating to remote Gerrit servers. This is the account on the REMOTE Gerrit server that has the ssh_private_key's corresponding public key registered. Can be overridden per-instance in gerrit_setup with 'ssh_user'. | no | gerrit |
| remote_ssh_port | SSH port for remote Gerrit servers (typically 29418). Can be overridden per-instance in gerrit_setup with 'ssh_port'. | no | 29418 |
| sync_on_startup | Trigger replication after startup | no | true |
| fetch_every | Interval for pull-replication polling (e.g., '60s', '5m'). The pull-replication plugin will poll the source Gerrit at this interval to fetch any new or changed refs. This enables automatic replication while keeping the web UI fully functional. Set to '0s' to disable automatic polling. | no | 60s |
| replication_timeout | Timeout for initial replication sync (in seconds) | no | 600 |
| sync_refs | Refs to synchronize (default: all branches, tags, changes) | no | +refs/heads/*:refs/heads/*,+refs/tags/*:refs/tags/*,+refs/changes/*:refs/changes/* |
| replication_threads | Number of replication threads per instance | no | 4 |
| max_projects | Maximum number of projects to fetch from remote Gerrit when no project filter is specified. Limits API queries for large instances. Set to a higher value if you need to replicate more projects. | no | 800 |
| skip_archived_projects | Skip archived (``READ_ONLY``) and hidden projects when fetching the project list from the source Gerrit. When ``'true'`` (the default) the action passes ``?state=ACTIVE`` to the source Gerrit's ``/projects/`` REST endpoint so archived projects are filtered out server-side and never get pre-created locally; pull-replication consequently does not mirror them, which can roughly halve initial sync time on instances that carry a large historical archive (ONAP is 181 active + 214 read_only = 395 total). Set to ``'false'`` to mirror archived projects too — necessary when debugging or backfilling a specific archived repository. | no | true |
| replicate_meta_refs | Mirror Gerrit NoteDb meta refs in addition to the normal heads / tags / changes refs. Required for the deployed CI Gerrit to render *open changes* (votes, comments, status), per-account identities and group memberships from the source server. Concretely, when ``'true'`` the generated ``replication.config`` gains: * ``+refs/meta/*:refs/meta/*`` and ``+refs/cache-automerge/*:refs/cache-automerge/*`` on every per-project remote (per-project ACLs + merge-preview cache). * A second ``[remote "<slug>-meta"]`` section targeted at ``All-Users`` and ``All-Projects`` that pulls a curated set of enumerated NoteDb refs: - ``refs/users/*``, ``refs/groups/*`` (account & group definitions) - ``refs/meta/external-ids`` (login → account_id map) - ``refs/meta/group-names`` (group UUID → name) - ``refs/meta/version`` (NoteDb schema pin) - ``refs/sequences/*`` (change-number sequence) - ``refs/draft-comments/*``, ``refs/starred-changes/*`` (per-user state) ``refs/meta/config`` is INTENTIONALLY EXCLUDED from the magic-repo remote. Pulling the source server's ``All-Projects:refs/meta/config`` would overwrite the deployed container's locally-bootstrapped global ACL and silently strip ``administrate-server`` from the bootstrap admin account, breaking the reindex / cache-flush REST calls and the admin UI on the deployed Gerrit. See the block comment in ``scripts/start-instances.py::generate_replication_config`` for the full rationale. Off by default because it materially increases initial sync size on instances with large review histories. Combine with ``reindex_after_sync: 'true'`` so the Gerrit Lucene index reflects the replicated NoteDb state in the UI. | no | false |
| reindex_after_sync | After the initial pull-replication sync completes, run an online reindex (and cache flush) inside each Gerrit container. Required for replicated changes to actually show up in the UI and search results, because Gerrit's dashboard queries hit the Lucene secondary index, not NoteDb directly. The reindex iterates over every replicated project and issues ``POST /a/projects/<name>/index.changes``, then flushes the ``accounts``, ``groups`` and ``external_ids_map`` caches via ``POST /a/config/server/caches/`` so newly replicated account / group refs become visible without a container restart. Has no effect when ``sync_on_startup`` is ``'false'``. Off by default; typically enabled together with ``replicate_meta_refs``. | no | false |
| require_replication_success | If true and sync_on_startup is true, the workflow will fail if replication verification fails. Set to false to allow the workflow to succeed even if replication issues are detected. | no | true |
| replication_wait_timeout | Maximum time (in seconds) to wait for replication to complete. Replication is considered complete when the repository count matches the expected count from the remote Gerrit server. Increase this value for large Gerrit instances. Only used when sync_on_startup is true. | no | 600 |
| exit | Stop containers when the job completes | no | true |
| check_service | Verify service availability after startup | no | true |
| enable_cache | Enable Docker layer and dependency caching | no | true |
| cache_key_suffix | Extra suffix for cache keys | no | "" |
| debug | Enables debugging output | no | false |
| use_api_path | When true, the local Gerrit container will use the same URL context path as the source/origin server (e.g., /r, /infra). This ensures that clone URLs and static content paths match the production server. When false, the container serves at root (/). | no | false |
| additional_plugins | Comma-separated list of extra plugin URLs to install | no | — |
| gerrit_init_args | Extra arguments for gerrit.war init | no | — |
| skip_plugin_install | Skip pull-replication plugin installation (testing) | no | false |
| ssh_auth_keys | SSH public keys to add for accessing the Gerrit container. One key per line, in standard authorized_keys format. When ssh_auth_username is also provided, a new Gerrit user account will be created with that username and these keys. Otherwise, keys are added to the default admin account. Example: ssh_auth_keys: | ssh-ed25519 AAAAC3... user@example.com ecdsa-sha2-nistp256 AAAAE2... another@example.com | no | "" |
| ssh_auth_username | Gerrit username to create for SSH access. When provided along with ssh_auth_keys, a new Gerrit user account will be created with this username and the provided SSH public keys. If not provided, ssh_auth_keys will be added to the default admin account (ID 1000000). Example: ssh_auth_username: 'myusername' | no | "" |
| ssh_auth_keys_secondary | Additional SSH public keys to register on a *second* Gerrit account, distinct from the one configured via ssh_auth_username / ssh_auth_keys. Intended for deployments that want to keep an automated bot identity (primary) separate from one or more human identities (secondary) on the same ephemeral Gerrit. The primary user typically owns the keypair whose private half is consumed by downstream GitHub Actions workflows (e.g. lfreleng-actions/gerrit-review-action), while the secondary user holds long-lived human keys (e.g. Secure Enclave-backed keys) for interactive SSH / UI access. When set, ssh_auth_username_secondary must also be set. Both fields use the same format as the primary pair. | no | "" |
| ssh_auth_username_secondary | Gerrit username to create for the *second* SSH account. Required when ssh_auth_keys_secondary is set; ignored otherwise. See ssh_auth_keys_secondary for the intended bot/human split. | no | "" |
| tunnel_host | External tunnel hostname for public access. Examples: 'bore.pub', Tailscale IP (e.g., '100.x.y.z'). When set along with tunnel_ports, Gerrit will be configured with external URLs for canonicalWebUrl and sshd.advertisedAddress. The tunnel should be started before invoking this action, pointing to the local ports (base_http_port, base_ssh_port). | no | "" |
| tunnel_ports | JSON object mapping instance slugs to their tunnel port assignments. Required when tunnel_host is set. Format: {"slug": {"http": 12345, "ssh": 54321}, ...} For single-instance setups, use the slug from gerrit_setup. The ports are the remote/public ports assigned by the tunnel service. Example: tunnel_ports: '{"lf-gerrit": {"http": 45678, "ssh": 45679}}' | no | "" |
| g2p_enable | Enable Gerrit to Platform (g2p) integration. When true, configures the gerrit_to_platform plugin inside the Gerrit container to dispatch GitHub Actions workflows in response to Gerrit events. | no | false |
| g2p_github_token | GitHub Personal Access Token (Fine-Grained) for the target organisation. Required permissions: Actions (read/write), Contents (read), Metadata (read). | no | "" |
| g2p_github_owner | GitHub organisation or user that owns the target repositories. Required when g2p_enable is true. | no | "" |
| g2p_remote_name_style | How Gerrit project names map to GitHub repository names in the replication config. Options: dash, underscore, slash | no | dash |
| g2p_remote_url | Override the GitHub remote URL pattern. Uses ${name} as the repository name placeholder. Auto-generated from g2p_github_owner when not provided. | no | "" |
| g2p_remote_auth_group | Gerrit authGroup for the GitHub replication remote. Must contain "github" for g2p platform detection. | no | GitHub Replication |
| g2p_comment_mappings | JSON object mapping comment keywords to workflow search filters for the comment-added hook. | no | {"recheck": "verify", "reverify": "verify", "remerge": "merge"} |
| g2p_hooks | Comma-separated list of Gerrit hooks to enable for g2p. Available: patchset-created, comment-added, change-merged | no | patchset-created,comment-added,change-merged |
| g2p_validation_mode | Controls behaviour when GitHub-side checks fail. Options: error, warn, skip | no | warn |
| g2p_validate_workflows | When true, checks that the target GitHub org has properly configured Gerrit workflows. | no | true |
| g2p_validate_repos | Comma-separated list of GitHub repositories to check for Gerrit workflow configuration. | no | "" |
| g2p_ssh_private_key | SSH private key for GitHub push-based replication. When not provided, a keypair is auto-generated. | no | "" |
| g2p_github_known_hosts | SSH known hosts entries for github.com. Auto-fetched via ssh-keyscan when not provided. | no | "" |
| g2p_org_setup | Controls GitHub org verification and auto-provisioning. Options: provision - Audit AND always-overwrite required org secrets and variables on every run, even when they already exist. Overwrite is deliberate because each container build produces a fresh ephemeral SSH key and may bind to different tunnel host / ports between runs; leaving stale values on the GitHub side would silently break downstream workflows. Use `g2p_org_token_map` to supply an elevated token per org. verify - Audit and report only (default). No writes to the GitHub org. skip - Do not audit org configuration. | no | verify |
| g2p_org_token_map | Base64-encoded JSON array mapping GitHub org names to PATs for org-level provisioning. Recommended when g2p_org_setup is 'provision' so each target org can use a dedicated admin:org-scoped token; otherwise g2p_github_token is used as a fallback. JSON schema (pre-encoding): [ {"github_org": "my-org", "token": "ghp_xxx..."}, {"github_org": "other-org", "token": "ghp_yyy..."} ] Encoding (whitespace is tolerated; single line or wrapped both work): printf '%s' "$JSON" | base64 Store the resulting string as a repo/org secret (e.g. G2P_ORG_TOKENS) and pass it via this input. See docs/GITHUB-ORG-VERIFY-CONFIG.md for details. | no | "" |
Outputs
| name | description |
|---|---|
| container_ids | JSON array of running container IDs |
| container_ips | JSON array of container IP addresses |
| instances | JSON object mapping slug to instance details {cid, ip, http_port, ssh_port, url, api_path, api_url} |
| gerrit_urls | Comma-separated list of Gerrit HTTP URLs |
| api_paths | JSON object mapping slug to API path details {gerrit_host, api_path, api_url} for each instance. The api_path is the URL prefix (e.g., /r, /infra, /gerrit) detected or provided for each Gerrit server. |
| ssh_host_keys | JSON object mapping slug to SSH host public keys. Contains the auto-generated SSH host keys for each Gerrit instance, which can be used by downstream steps for automation tasks. Format: {slug: {ssh_host_rsa_key: "...", ssh_host_ed25519_key: "...", ...}} |
| g2p_enabled | Whether G2P integration ran |
| g2p_config_path | Path to generated INI inside container |
| g2p_hooks_enabled | JSON array of hooks that got symlinks |
| g2p_github_owner | Configured GitHub owner |
| g2p_remote_name_style | Configured repository name style |
| g2p_validation_results | JSON array of GitHub check results |
| g2p_token_provided | Whether a GitHub token was supplied |
| g2p_ssh_public_key | Public key for downstream deploy-key setup |
| g2p_org_audit_results | JSON array of org-level audit check results. |
| g2p_org_provisioned | Whether any org items were auto-provisioned. |