Publishing to Gitea and Gerrit from Backstage templates

Gitea publishing usually runs under a dedicated account whose access token the scaffolder uses to create repositories, set options and push the initial commit. The token's scope decides what a template can do, so the goal is the narrowest set of permissions that lets the action complete. Confirm the exact scope names in the Gitea documentation for your release line, because the names and their grouping change between versions.

• Dedicated bot account: Create a service user for Backstage rather than reusing a personal token, so audit logs and revocation stay separate from people.
• Repository scope only: Grant the token the repository write permission needed to create and populate repositories, and avoid administrative or user-management scopes.
• Organization membership: The account must be a member of the target organization with rights to create repositories there, which is the main placement control.
• Token storage: Store the token in your secrets store and inject it into the Backstage backend configuration, never in the template repository.
• Rotation plan: Record who owns the token and how it is rotated, since a scaffolder run fails silently when a token expires.

Before writing scope names into configuration, check them against the Gitea documentation for the version you run.

On Gitea, placement is mostly an organization question. A template should name a target organization and, where teams split by domain, a naming convention that tells owners apart at a glance. Because the token belongs to a member of that organization, the same account determines where every new repository lands, so one service account per organization boundary is easier to reason about than one account spanning many.

• Organization per boundary: Map each template's destination to one organization, for example by business unit or by sensitivity tier, and keep the mapping in the template parameters.
• Restricted parameter values: Offer a fixed list of organizations in the form instead of free text, so a typo does not create a repository in the wrong place.
• Team permissions: Grant the owning team write access through Gitea team settings after creation, and keep that step in the template so ownership is never left blank.
• Visibility default: Set repositories to private by default and make any change to visibility an explicit parameter.
• Catalog registration: Use the registered repository URL to link the new component to its owning group in the catalog.

If you run Gitea Enterprise features such as organization-level branch protection inheritance, confirm with the vendor how they apply to repositories created by automation.

Gerrit is organized around projects and access groups rather than repositories and organizations, and it accepts changes through review rather than direct pushes to protected branches. A Backstage template therefore needs a service account that can create projects and push the initial history, and it needs a decision about whether the scaffolder reaches Gerrit over HTTP or SSH. Confirm the transport options, authentication methods and permission names against the Gerrit documentation for your installed version.

• Service account: Create a dedicated Gerrit account for Backstage with its own SSH key or HTTP credential, and keep it out of human review groups.
• HTTP or SSH: Choose one transport per deployment, check which one your action module supports, and confirm that the chosen path is reachable from the Backstage backend network.
• Project creation rights: Grant the account the global or parent-level right to create projects only under the parent projects that templates target.
• Initial push rights: Check whether the account can push the first commit to a new project without a review, since many installations restrict direct pushes to refs such as the branch heads.
• Access groups: Assign the owning group read and submit rights on the new project through access groups rather than per-user grants.

A failed push often reflects a missing initial-push permission rather than a broken template, so test this path with a dry run on a non-production Gerrit first.

Gerrit placement is a parent-project decision. A new project inherits access rules from its parent, so the parent a template targets determines who can read, review and submit changes from the first commit. Templates should choose from a short list of approved parents and attach the owning access group at creation, since a project created without an owner is hard to govern later.

• Approved parent list: Limit the template to a fixed set of parent projects, and document which parent carries which inheritance rules.
• Naming scheme: Agree on project names that encode the parent and the owning team, so the catalog and Gerrit tell the same story.
• Owner group at creation: Set the owning access group as part of the publish step rather than as a manual follow-up.
• Label and submit rules: Confirm that the label and submit rules inherited from the parent match what the team expects before the first change arrives.
• Catalog link: Register the project URL in the catalog with the owning group so reviewers and auditors can trace ownership.

Ask your Gerrit administrators to confirm inheritance on a test project, because the effective permissions shown in the web interface are the reliable source, not the template.

Most DeployOpen engagements are fixed-scope, which means the scope, deliverables and timeline are agreed in writing before any build work starts. For a Gitea or Gerrit publishing job, that document should name the platform and version, the hosting model, the Backstage version in use, and each action module the templates will call. It should also state who creates the service accounts and tokens, where repositories will be placed, and which catalog entries are registered on success. The written scope is the reference point when a later question arises about whether something was included.

• Platform and version: Name the Gitea or Gerrit release line you run, and confirm it with your platform owner before the scope is drafted.
• Action modules: List the exact publishing actions each template uses, so nothing is assumed about GitHub or GitLab behavior.
• Responsibilities: Record who provisions credentials, who approves template changes and who owns the resulting repositories.
• Exclusions: Write down what is out of scope, such as Gerrit label policy redesign or Gitea Actions pipeline authoring.
• Acceptance criteria: Agree how a successful run is judged, for example a repository created, a catalog entry registered and a clean dry run.

Ask for the written scope to be reviewed by your security and platform leads before signing, since credential scope is often the item that changes most during review.

Before any template reaches every developer, DeployOpen proposes building one pilot template against your self-hosted Git platform. The pilot exercises the whole chain: parameter form, skeleton fetch, repository creation, catalog registration and the output links shown on success. Choosing a single, representative service type keeps the pilot small enough to review line by line while still touching the parts that differ between Gitea, Gerrit and the GitHub or GitLab examples most teams start from.

• Representative service: Pick one service type that your teams create often, so the pilot reflects real parameters rather than a toy example.
• Platform differences: Confirm how the Gitea action creates repositories and how Gerrit projects and permissions are handled, instead of copying a GitHub step.
• Credential path: Test the token or account the action uses, including its scope, on a non-production instance.
• Review checkpoints: Agree who signs off the pilot and what changes are expected before it is copied for other teams.
• Illustrative example: A payments squad template might create one Gerrit project per service with a fixed naming pattern, reviewed before wider rollout.

Ask the team to confirm the exact action names and versions they will run, because these depend on the Backstage release in use.

Dry-run testing lets the team check a template without creating repositories or webhooks on the Git platform. DeployOpen uses dry-run support in the actions, branches that check the dry-run context flag, and unit tests for handlers, so that each publishing step can be verified before the real platform is touched. The output is a record of what the template would have done, which the platform owner can review alongside the template definition.

• Dry-run support: Confirm each custom or module action reports its intended effect in dry-run mode rather than calling the platform.
• Handler tests: Write unit tests for the handlers that build repository names, paths and settings from the parameters.
• Negative cases: Test duplicate names, missing permissions and invalid parent groups, since these are where Gerrit and Gitea errors differ.
• Review process: Route each template change through a named reviewer who did not write it.
• Gating: Keep the template out of the general catalog until dry runs pass on the target instance.

Ask for the test results and dry-run output to be kept with the template version, so an auditor or future maintainer can see what was verified.

At handover, DeployOpen delivers documentation that lets your own engineers run, change and troubleshoot the publishing templates without the original builders. The documentation covers the template structure, each action module and its configuration keys, the credential model, and the steps to add a new Gitea or Gerrit target. It is written against your environment, with your hostnames, group names and naming conventions, and it records the decisions behind them.

• Configuration reference: List each setting, its owner and where it is stored, without placing secrets in the document.
• Credential procedure: Explain how tokens or accounts are rotated, who can request a change and how old credentials are revoked.
• Runbook: Cover common failures, such as a repository name already taken or a token that lacks permission, with the checks to run first.
• Version record: Note the Backstage and action module versions tested, so the next upgrade starts from a known state.
• Ownership map: Name the team that owns each template and the escalation path for platform changes.

Check that the documentation is stored in a location your team controls and that someone on your side is named as its owner.

Upgrades to Backstage, action modules and the Git platform itself continue after handover. DeployOpen offers ongoing support and upgrades as an optional retainer, which is separate from the fixed-scope build. Under a retainer, the work typically covers reviewing upgrade notes, re-running dry-run tests against new versions and adjusting templates when action interfaces change. The scope of any retainer is agreed in writing, like the original engagement.

• Release tracking: Watch Backstage and the Git platform release lines, and assess their effect on the publishing actions.
• Regression runs: Repeat the dry-run and pilot checks after each upgrade before templates are republished.
• Template changes: Adjust parameters or steps when a platform adds or removes an API the action depends on.
• Support boundaries: Define response expectations and which incidents are covered.
• Internal capacity: Decide what your own team will keep doing, so the retainer does not carry routine tasks you can handle.

Ask for the retainer scope to state which Backstage and platform versions it covers and how upgrades are priced, since these determine recurring cost.