Templates and self-service actions

A template turns inputs into a proposed change

A self-service template defines fields a user fills in and steps a backend runs. In this course, its first output is a draft PR, not a direct cluster mutation. That gives the learner a visible diff and preserves the existing review process.

Restrict the request to supported choices

The first template accepts a request ID and targets only the local environment. It writes a reviewable overlay change in the allowed repository. It does not accept arbitrary URLs, shell commands, cluster contexts, or production destinations.

Backstage Software Templates define parameters and execution steps. Available actions depend on installed backend modules; inspect the instance's action catalog before assuming a GitHub action exists. Install and configure the required backend integration before using it from template YAML.

Separate input checks from authorization

A dropdown improves input quality but does not authorize a user. Configure backend authentication and permissions for templates, actions, and destinations. Repository permissions and branch rules remain necessary after the portal accepts a request.

The capstone's first action generates files and opens a PR. That makes the requested change inspectable before it affects a cluster. A unique request ID lets operators trace repeated submissions; it does not by itself implement idempotent execution. The chosen action must define how an existing branch or request is handled.

Follow one input through the template

The capstone accepts requestId, validates its format and inserts it into a fixed local annotation patch. The selected repository, target branch and output path are configured by the maintainer. The user is not allowed to submit a shell command or choose a production cluster.

Predict a duplicate request. Reusing an ID may select an existing branch; the action must report the collision or follow an explicit update policy. A unique-looking ID field alone does not implement idempotency, which means repeated requests have the intended bounded effect rather than creating uncontrolled duplicates.

Before enabling Git publication, use the template's dry-run facility and inspect the generated path and diff. Expect only the intended annotation patch. If it changes an image, secret or destination, stop and repair the template before granting it credentials.

Try it

Preview the template output before enabling publication. Inspect every generated path and confirm it changes only the intended local overlay. Test an invalid ID, an unsupported environment, a repeated ID, and a repository-integration failure.

Next, open a PR against a repository you control using a narrowly scoped integration. Confirm branch rules still require the intended checks and review. Keep the portal’s permissions scoped to the Git workflow; creating this PR does not require cluster-admin access.

Checkpoint and revision

Explain what happens after a partial failure: files generated but no PR, PR created but policy failed, or merge accepted but sync failed. Each state needs a visible result and a recovery action, not a generic success notification.

Compare your reasoning

A dropdown limits normal input but does not authorize a user. Backend permissions and repository controls still matter. The form can finish while the deployment is pending, so its result should say “PR created” and link to the next stage.

Sources

Backstage writing templates↗, Backstage built-in actions↗, Backstage template permissions↗.