Backstage and Gerrit integration

How Backstage connects to Gerrit for catalog discovery and project publishing

If your organization standardized on Gerrit for code review and wants its services visible in Backstage, the integration does two jobs. It reads catalog files from Gerrit repositories so that each service appears as an entity in the software catalog, and it publishes new projects into Gerrit when a team runs a Software Template. Gerrit is listed in the Backstage integrations documentation, which means the connection is a supported integration point rather than a community workaround. Both halves ship as modules in the core Backstage repository: catalog-backend-module-gerrit handles discovery, and @backstage/plugin-scaffolder-backend-module-gerrit supplies the scaffolder actions that create projects.

On the catalog side, the Gerrit catalog module scans configured Gerrit servers for catalog-info.yaml files and turns them into entities. Your platform team decides which Gerrit hosts, projects and branches the backend may read, and that choice sets how much of your code estate becomes visible in the portal. The scaffolder side is narrower: the Gerrit actions create the project and push the template skeleton from a Software Template run. Both halves depend on a service account with read access for discovery and, for publishing, the permission to create projects, so confirm with your Gerrit administrators which account and access level your policy allows before you design either flow.

The scope of this section is reading and writing repositories from Backstage. It does not cover administering Gerrit itself, including server installation, access group design, submit rules, replication or plugin management on the Gerrit side. Those remain your Gerrit team's responsibility, and the Backstage configuration should be planned against the access model they already run. Confirm the exact Gerrit server version and the module versions you need against the Backstage release you plan to deploy, because the supported combinations are set by the Backstage project rather than by this page.

What you need before connecting Gerrit to Backstage

Connecting Backstage to Gerrit depends on four things lining up: a Backstage instance you can upgrade, a Gerrit identity the backend can use, a network path and trust chain between the two, and a repository convention for catalog files. Settle these before configuration so the catalog module has something reliable to read.

A running Backstage instance

Start from a Backstage deployment on a supported release line, not a demo app. The versioning policy ships a main release line monthly and a next line weekly, so confirm which line your team tracks and that your app's @backstage packages move together with yarn backstage-cli versions:bump. Check that the Gerrit catalog module version matches the Backstage version you run before you add it.

Gerrit service account credentials

Create a dedicated Gerrit service account for the Backstage backend rather than reusing a personal login. Ask your Gerrit administrators which authentication method they permit for automated HTTP access, and request read-only visibility on the projects Backstage should discover. Store the credential in your secrets system, not in the repository holding app-config files, and record who owns its rotation.

Network path from the backend

The Backstage backend, not the browser, calls Gerrit to read catalog files and list projects. Confirm that the host running the backend can reach the Gerrit HTTP endpoint on the port and path your administrators use, including any reverse proxy or load balancer in front of Gerrit. Test the path from the same network segment and container runtime that will run Backstage in production.

TLS trust for internal certificates

If Gerrit uses a certificate issued by an internal certificate authority, the Node.js process running the backend must trust that chain. Export the root and intermediate certificates from your PKI team and plan how they reach the backend image, such as a mounted bundle or a build step. Certificate errors often look like catalog failures, so verify the trust chain before debugging the module itself.

Confirmed Gerrit compatibility and endpoints

Do not assume which Gerrit versions or API endpoints the integration supports. Read the Backstage integrations documentation for the Gerrit section, then confirm the exact Gerrit server version, the API paths your installation exposes, and any differences between your Gerrit deployment and the defaults. Record the answers in your architecture notes so later upgrades of either system are tested against known behavior.

Agreed catalog-info convention

Decide where each repository keeps its catalog-info file, what the default branch and path are, and which entity kinds teams must declare. Gerrit projects often hold several changes in review, so state whether discovery reads only the default branch. Agree on an owner field that matches your identity directory so ownership in the catalog resolves to real groups and users.

Configuring the Gerrit integration step by step

This sequence connects a Backstage instance to your Gerrit server so catalog files are read from repositories, projects are discovered on a schedule, and new projects can be published from Software Templates. Each step ends with a check you can run before moving on.

Confirm Gerrit access and service account scope
Your Gerrit administrator and the DeployOpen team agree on a dedicated service account, its HTTP credentials and the projects it may read and create. Confirm with your Gerrit administrator that the account can list projects and read the branches you plan to scan, and that write rights are limited to the namespaces your templates will use. Record the Gerrit host URL and the credential handling method your security team approves. The step is done when the account can authenticate to the Gerrit REST interface from the host that will run Backstage and return the project list for a test project.
Register the Gerrit host in integrations configuration
A Backstage developer adds a Gerrit entry under the integrations section of app-config.yaml, with the host, the base URL and the credentials supplied from environment variables rather than written into the file. Exact key names and the expected structure are in the integrations documentation, which should be checked against the Backstage version you run. Keep secrets in your secret store and inject them at runtime. The step is done when the backend starts without integration errors and the Gerrit host appears in the integrations configuration that the backend loads.
Add the Gerrit catalog module to the backend
A backend developer installs the Gerrit catalog module from the Backstage core repository, typically @backstage/plugin-catalog-backend-module-gerrit, and registers it in the catalog backend alongside the existing modules. The module is part of the same release line as the rest of your @backstage packages, so install it with the matching version rather than pinning a separate one. Confirm the package name against the plugins directory of the core repository before you install. The step is done when the backend builds and starts with the module loaded and no unresolved import errors appear in the logs.
Set discovery locations and filters
A platform engineer defines the Gerrit provider configuration in app-config.yaml, listing which projects, branches and catalog file paths the scanner reads, and adds filters that exclude archived, personal or experimental projects. Start with one project prefix so the first scan stays small. Agree the file name and location for catalog descriptors, usually a catalog-info.yaml file on the default branch, with your repository owners. The step is done when a refresh of the catalog logs a count of discovered locations that matches the projects you expected to include, and the excluded projects do not appear.
Verify catalog reads with a test entity
A platform engineer commits a minimal catalog-info.yaml to a sandbox Gerrit project, waits for the next scheduled scan or triggers a manual refresh, and checks the catalog for the resulting Component entity. Confirm that the owner, lifecycle and source location fields resolve to the expected values. Then remove the file and confirm the entity is marked as an orphan or removed according to your catalog settings. The step is done when the test entity appears with the right metadata and its source link opens the file in Gerrit.
Add the scaffolder publish module for templates
A backend developer installs the Gerrit scaffolder action module, @backstage/plugin-scaffolder-backend-module-gerrit, which provides the actions a Software Template uses to create repositories and push initial content. The module is listed among the built-in actions in the scaffolder documentation, so check that action names match your installed version before you write template steps. Register the module in the scaffolder backend with the same credentials used for reads, or a separate account if your policy requires it. The step is done when the scaffolder backend starts and lists the Gerrit actions in its action registry.
Test a template that creates a sandbox project
A template author runs a test Software Template that calls the Gerrit publish action against a sandbox Gerrit namespace, with a project name and parent chosen for testing. The test should confirm the project is created, the initial commit is pushed to the expected branch, and the generated catalog-info.yaml is registered so the new project appears in the catalog after the next refresh. Remove the sandbox project afterward. The step is done when the Gerrit project, its initial commit and the catalog entry all appear as expected in one run.
Record the configuration and confirm the handover
The team records the final integration settings, credential owner, rotation procedure and the list of projects in scope, then hands the configuration to the operations group that will run Backstage. Confirm with your Gerrit administrator who owns the service account and how credential rotation is scheduled. Keep the sandbox test template in a non-production space for future regression checks after upgrades. The step is done when the operations owner has a written record of the configuration and has run the read and write checks once in their own environment.

How Gerrit catalog discovery finds catalog-info files

The Gerrit catalog module finds catalog descriptors in three steps. It asks the Gerrit server which projects fall within the configured scope, fetches the descriptor files from the paths you set for each project, and registers the resulting entities with the Backstage catalog. The module is part of the core Backstage repository as catalog-backend-module-gerrit, so it ships with the same release line as the rest of your portal. Before you design anything around it, check the Backstage integrations documentation and the module source in your version to confirm which scope filters are available, such as project prefixes or access state, and how branches are read. Decide early which branch holds the authoritative descriptor, because a file that exists only on a feature branch will not be treated as a published component.

Refresh timing decides when a change in Gerrit becomes visible in the portal. Discovery runs on the catalog's scheduled refresh for the provider, so a new catalog-info.yaml merged to a project will appear after the next scheduled pass, not at the moment of merge. Ask your team to confirm the interval in its Backstage version, and measure how long a full pass takes against your project count, since each pass adds read load on the Gerrit server. If the version you run supports event-driven updates for Gerrit, confirm that before you promise teams faster visibility, because polling is the behavior you can rely on without further verification. Tell service owners the expected delay so they do not treat a missing entity as a failed registration.

Renamed and removed projects need a deliberate plan. Backstage tracks each entity against the location it came from, so when a project disappears from scope or its descriptor is deleted, the expected result is that the entity is flagged as orphaned rather than silently erased, and a renamed project usually shows up as a new entity while the old one becomes orphaned. Confirm this behavior for the Gerrit module in your release, including how long orphaned entities remain and whether they keep their relations, because dependent services can break if those links disappear. Before a large Gerrit reorganization, agree on who reviews orphaned entities, how ownership moves to the new project, and whether catalog cleanup is manual or automated.

Mapping Gerrit projects, files and actions to Backstage entities

This table compares each Gerrit object with the Backstage entity, file or template field it maps to, and shows whether the value comes from the catalog descriptor or from the Software Template. Read it as a checklist for the catalog design and the publish step, and confirm the owner mapping against your identity source before you load any users or groups.

Gerrit or Backstage item	Mapping in Backstage	Set by	What to confirm
Gerrit project	Component or Resource entity, one entity per project that holds a catalog file	Catalog descriptor, discovered by the Gerrit catalog module	Which projects are in scope and whether each one has a catalog-info file
catalog-info file in project	Descriptor file read from the repository, defining kind, metadata and spec	Repository owners, committed to the project	File path and branch the discovery reads, and that the file is valid YAML
Entity kind	Component for services and libraries, Resource for infrastructure such as databases or hosts	Descriptor kind field	Which kind each project type uses under your catalog model
Owner reference	spec.owner pointing to a Group or User entity in the catalog	Descriptor, set by the project team	Whether the Gerrit group name matches a Backstage group name in your identity source
Gerrit group or project owner	Not a Backstage entity by itself, needs a matching Group or User entity to resolve	Identity source or org data import, not Gerrit discovery	How group names are normalized and who maintains the group list
Template parameters	Form fields in the Software Template, such as project name, parent project and owner	Template author and the user who runs the template	Which fields are required, and which values are validated against Gerrit before creation
New Gerrit project	Created by the Gerrit scaffolder action during the template run, then discovered like any other project	Template steps, using the Gerrit publish action	Credentials used for creation, default permissions, and whether the new project gets a catalog-info file

Securing the Gerrit credentials and publish path

A Gerrit integration gives Backstage read access to your code review server and, through templates, write access that creates new projects. The controls below limit what the backend can see and do, and make every read and publish traceable. Review them together, because a weak credential or an unreviewed template undoes the protection of the others.

Dedicated least-privilege service account

Create a separate Gerrit service account for the Backstage backend instead of reusing a personal or administrator login. Grant only the project read rights needed for catalog discovery, and add create-project or push rights only if you publish from templates. Confirm with your Gerrit administrators which global capabilities the account inherits, because group membership often grants more than project-level permissions suggest.

Scope the projects and branches read

Limit discovery to the Gerrit projects that hold catalog files, and to the branches the catalog should trust, usually the default branch. Review what the Gerrit catalog module is configured to search, so that experimental or private repositories do not become visible portal entities. Re-check this scope whenever new projects are created under a parent project.

Protect credentials in Backstage configuration

Store the Gerrit username and HTTP password or token in environment variables or your secret manager, and reference them from the integration configuration rather than writing them into app-config.yaml. Keep production configuration files out of the frontend bundle, and rotate the credential on a schedule your security policy sets. Confirm that logs and error messages do not echo the token during failed discovery runs.

Limit who can run publishing templates

Software Templates that call Gerrit publish actions create repositories on your behalf, so restrict who can execute them to the teams that own the workflow. Use Backstage permission policies to separate viewing a template from running it, and bind template execution to groups that come from your identity provider. Do not let every signed-in user start a publish job.

Consistent identity and no guest access

The Backstage authentication guidance advises sign-in resolvers that map every provider to the same identity, and recommends against guest access in production. Without that consistency, the same person can appear as two users, and the audit trail for a template run becomes hard to attribute. Verify that each sign-in path resolves to the catalog user that owns the resulting actions.

Review publishing and audit trails on both sides

Treat template publishing as an automated change and review its template, parameters and target project before release, as you would a pipeline change. Then compare the Backstage execution log with the Gerrit event history for the service account, so you can confirm each created project matches a known run. Confirm your log retention on each side meets your change management requirements.

Common Gerrit integration failures and their fixes

This table lists the failures teams most often hit when Backstage reads from or publishes to Gerrit, with the likely cause and the first check for each. Work down the rows in order, since a credential problem can hide every symptom that follows it. For deeper diagnosis, use the operations and troubleshooting guidance for Backstage.

Failure	Likely cause	First check
Authentication errors from the service account	The Gerrit HTTP credential is expired, belongs to a different account than configured, or lacks read access to the projects being scanned	Confirm the configured username and password or token by making a direct authenticated request to the Gerrit host from the Backstage backend container
Catalog files not found	The discovery path or branch filter does not match where catalog-info files actually live, such as a custom default branch or a nested directory	Compare the configured branch and path pattern with one real repository, then check the backend log for the URL the Gerrit catalog module requested
Entities missing after refresh	Projects are excluded by a filter, the repository has no catalog file on the matched branch, or the descriptor fails validation	Check the processing errors for the entity location in the catalog, then re-run validation on the descriptor file locally
Duplicate or stale entities	The same descriptor is registered in two places, or a deleted file is still referenced by an older location entry	Search the catalog for the entity name, list its locations, and remove the redundant registration or orphaned location
TLS errors with internal certificates	The Gerrit server uses a certificate issued by an internal CA that the Backstage backend container does not trust	Confirm the CA bundle is mounted into the backend container and that the Node.js process trusts it, then test the connection from inside that container
Scaffolder publish fails on permissions	The service account cannot create projects, push the initial commit, or add the owning group as a project owner	Test project creation and first push manually with the same account, then check the Gerrit project and group permissions for that account
Publish succeeds but the new project is not discovered	The template wrote the catalog file to a branch or path outside the discovery filter, or the catalog has not yet refreshed	Verify the catalog file location in Gerrit, then confirm the discovery schedule and the branch the template committed to
Sign-in works but Gerrit actions still fail	Sign-in uses a different identity than the integration service account, so users are not mapped to Gerrit accounts used by the actions	Confirm which credential the scaffolder action uses for the publish step, separately from the user who started the template

Questions teams ask before connecting Gerrit to Backstage

How much effort does a Backstage and Gerrit integration take?

Effort depends on how many Gerrit projects and repositories Backstage must discover, how many catalog files already exist, and how many Software Templates will publish new projects to Gerrit. A small setup that reads catalog files from a handful of projects is a different job from a discovery run across hundreds of projects with custom scaffolder actions. The main drivers are the number of projects, the number of templates, any custom actions your templates need, and how identities from Gerrit map to Backstage users and groups. Ask the implementer to break the work into discovery, publishing and identity mapping so each one can be scoped and priced separately.

Can an internal team connect Gerrit to Backstage without outside help?

Yes, if the team already runs Backstage in production and has engineers who understand the catalog and the Gerrit server. The Gerrit catalog module and the Gerrit scaffolder actions come from the Backstage core repository, so the work is configuration, testing and governance rather than building a new integration. Outside help is most useful for the parts that are easy to get wrong: credential design for the Gerrit service account, catalog file conventions across many teams, template testing, and a repeatable upgrade path. Many organizations split the work, keeping day-to-day ownership in house and engaging a partner for the initial design and review.

What does the work need from Gerrit administrators and Backstage owners?

Gerrit administrators need to create a dedicated service account with read access to the projects Backstage should discover, and write access only where templates will create new projects. They also need to agree on the catalog file path and naming convention in each repository, and confirm how the Gerrit server is reached from the Backstage backend. Backstage owners need to add the integration configuration, decide which catalog locations are loaded, define the entity model for Gerrit projects, and own the templates that publish new projects. Both groups should review the access model together before any credentials are issued.

How long does a Gerrit integration take to deliver?

Duration follows the same drivers as effort: the number of projects to discover, the number of templates to publish, how many custom actions are needed, and how quickly decisions about identity mapping and catalog conventions are made. Delays usually come from waiting on access approvals, agreeing on who owns each project entry, or finding that existing repositories lack catalog files. Ask for a timeline that lists these dependencies as separate milestones, and check that it allows for testing the templates against a non-production Gerrit server before they publish to production projects.

Does Backstage have a paid edition that includes Gerrit support?

No. Backstage is an open source framework released under the Apache License 2.0, and the project itself does not offer a paid edition. The Gerrit catalog and scaffolder modules are part of the open source repository, so there is no license fee for the software. Costs come from the infrastructure that runs Backstage, the time spent configuring and testing the integration, and any external services you engage. Confirm with your procurement team that any third-party plugins or hosted services you add carry their own license terms, since those are separate from Backstage itself.

What should I ask for in a written quote for this integration?

Ask for a written scope that names the Gerrit server version and hosting model, the number of projects to discover, the list of templates that publish to Gerrit, and every custom scaffolder action included. Request a breakdown of the one-time work (design, configuration, template authoring, testing and handover) and the recurring work (upgrades, template maintenance and support, if you need it). Confirm what the quote excludes, such as Gerrit server administration or identity provider changes, who provides test environments, what documentation and training you receive, and how changes to scope are priced. Ask how acceptance will be verified before work is closed.

How does Gerrit identity mapping affect ownership in the catalog?

Ownership in Backstage depends on whether the users and groups that own catalog entities match the identities your organization uses everywhere else. The Gerrit integration reads repository content, so ownership references in catalog files must point to users and groups that exist in your directory or catalog. If Gerrit account names do not match your identity provider, ownership will break and entities will show no owner. Decide the mapping rule before discovery begins, and confirm whether org data comes from Gerrit, a directory service, or both. The authentication documentation also recommends sign-in resolvers that resolve each provider to the same identity.

How DeployOpen scopes and delivers the Gerrit integration

DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, including Backstage. For a Gerrit integration, we start from your Gerrit servers, your catalog file conventions and the templates your teams already use, then agree the work in writing before any build starts.

How we scope

Inventory the Gerrit servers, projects and access accounts the Backstage backend must reach.
Agree which repositories and branches are searched for catalog files and which are excluded.
Define which Gerrit actions software templates may use, and who approves new project creation.
Confirm the written scope, deliverables and timeline with you before implementation begins.

How we build

Configure the Gerrit integration and catalog discovery in your Backstage deployment under your own credentials.
Build and test any scaffolder steps for publishing new projects from templates to Gerrit.
Verify that discovered entities, ownership fields and template outputs match the agreed design.
Keep sign-in and organization data configuration separate from Gerrit access so each can be reviewed alone.

How we hand over

Document the integration settings, credential scopes, catalog file conventions and template behavior.
Provide a runbook covering discovery failures, credential rotation and common configuration errors.
Walk your platform and engineering teams through the deployed configuration and how to change it.
Deliver test evidence and configuration records your internal reviewers and auditors can inspect.

How we support

Plan Backstage upgrades that keep the Gerrit modules aligned with the rest of the @backstage packages.
Review Gerrit server upgrades and access changes for effects on discovery and publishing.
Ongoing support, upgrades and continuous testing are available as a retainer, scoped in writing.
Ask any provider, including us, to confirm module compatibility with your Gerrit version before a change.