Platform Engineering: Validate One Golden Path Before Building a Portal

Updated August 10, 2026. Intended for engineering leaders and platform teams whose developers repeatedly need help finding service ownership, creating repositories, or reaching a first deployment.

Problem definition: A new service can become a chain of private messages when ownership, repository setup, deployment rules, and operating documentation live in different places. Platform engineering can reduce that friction, but it is not a reason to build a company-wide portal. It is a way to make one frequent, safe workflow self-service and observable.

Recommendation: start with one service type and a four-week pilot

Use a catalog plus a scaffolded golden path when several teams create the same kind of service and the first deployment requires repeated manual handoffs. Start with one bounded service type, such as an internal Node API. Do not start by registering every system or by automating production access.

Do not choose Backstage first if one or two teams already have a stable repository template and deployment path. In that case, repair the documentation and shared CI template before adding a catalog product to operate.

What the system must do—and what it must not do

A useful internal developer platform has three separate responsibilities. The catalog makes ownership and relationships findable. The software template creates a reviewed starting point. The delivery system performs privileged work under its own identity and approval rules.

Layer	Job	Guardrail
Catalog	Show owner, lifecycle, system, and operating links.	Require a verified owner before a component is eligible for automation.
Template	Create a repository, baseline documentation, and CI configuration.	Keep secrets and production credentials out of template inputs and generated files.
Delivery	Deploy reviewed changes.	Use a separate CI identity, protected environments, approvals, and audit logs.

Backstage documents the catalog as a model for software entities and relationships, and its Scaffolder as a templated software-creation workflow. Those capabilities connect discovery and creation; they do not remove the need for authorization design.

The design trade-off: catalog plus path, shared CI only, or manual requests

Approach	Use it when	What you gain	What you give up
Manual requests and a wiki	Changes are rare and the team is small.	Low initial operating cost.	Knowledge and ownership drift.
Shared CI templates	Deployment consistency is the only repeated problem.	Fast standardization with little platform overhead.	No unified way to discover services or their owners.
Catalog plus one golden path	Multiple teams repeatedly create a known service type.	Discovery and creation are connected and measurable.	Someone must maintain entity quality, templates, and upgrades.

My recommendation is the third option only after the second option is already a reliable building block. A platform team becomes a bottleneck when it replaces self-service with a nicer-looking request queue.

Four-week execution plan

1. Week 1: record the baseline. For the five most recent services of the chosen type, record elapsed time from repository request to first non-production deployment, number of human handoffs, and changes that had to be reverted. Do not claim an improvement before this baseline exists.
2. Week 2: add the smallest catalog contract. Require an owner, system, lifecycle, and operating-document link. Leave incomplete entries out of the pilot.
3. Week 3: build one reviewed template. Generate only a repository, README, service manifest, and CI configuration. Make a pull request review the generated workflow before it becomes the default.
4. Week 4: run real users through it. Ask at least three developers to create the chosen service type. Record where they stop, which exceptions they need, and whether the platform team received new manual work.

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: orders-api
spec:
  type: service
  lifecycle: experimental
  owner: team-commerce
  system: commerce

This is deliberately small. Add fields only when an owner can keep them accurate and a user has a decision to make with them.

Secure the handoff from template to deployment

A template may create a repository, but it should not receive standing production credentials. GitHub’s OIDC guidance describes exchanging a short-lived workflow identity for cloud access instead of storing long-lived cloud credentials in GitHub. Bind that identity to a specific repository, branch or environment, and approval policy.

1. Create repositories with a narrowly scoped GitHub App or template-specific token.
2. Run build and test with the generated CI workflow.
3. Require a protected environment approval before any production deployment.
4. Use OIDC federation for the deployment identity; restrict cloud trust conditions to the approved repository and environment.
5. Write the run URL, actor, commit SHA, and outcome to the change record.

If deployment fails, inspect the existing change and audit trail before rerunning the template. Re-running creation workflows can leave duplicate repositories, identities, or cloud resources.

Failure patterns and recovery

1. Registering everything first. Stale owner data makes the catalog untrusted. Recover: register only pilot services; enforce owner review in pull requests.
2. Calling the golden path a mandatory architecture. Special cases will route around it. Recover: publish an explicit out-of-scope path and owner for exceptions.
3. Giving scaffolding cloud-admin access. A creation error becomes a cost or security incident. Recover: separate creation, deployment, and operations identities; require approval for high-risk steps.
4. Measuring generated repositories only. A fast start can still create remediation work. Recover: measure first-deployment lead time, manual interventions, and seven-day template-fix requests together.

Cost and operating conditions

The first cost is not the portal host. It is the recurring work to keep ownership, templates, and integrations trustworthy. Budget an explicit maintainer, a template release process, and a regular review of catalog fields. A small team can often achieve the same result with a repository template, a short ownership file, and shared CI.

Backstage is a good fit when the problem is cross-team discoverability plus repeated creation paths. It is a poor fit when the organization has not agreed who owns a service or when the underlying delivery pipeline is unreliable.

Limits and further study

A catalog does not discover an accurate organization chart by itself, and a template does not make an outdated architecture safe. Treat it as operational product work, not an installation project.

• Backstage Software Catalog documentation — entity and relationship model, accessed August 10, 2026.
• Backstage Software Templates documentation — Scaffolder workflow and template concepts, accessed August 10, 2026.
• GitHub Actions OIDC security guidance — short-lived cloud identity pattern, accessed August 10, 2026.

Related AQ-Score guides

• GitHub Actions OIDC deployment guide
• Third-party coding agent security validation
• Keeping team instructions with the codebase

Implementation checklist

• One service type and an explicit out-of-scope list are chosen.
• Five recent services provide a baseline for handoffs and first deployment.
• Every pilot component has a verified owner, system, lifecycle, and operating link.
• Generated CI is code-reviewed and contains no secret values.
• Repository creation and deployment use separate, least-privilege identities.
• Production deployment requires a protected environment and produces an audit trail.
• Three developers complete the pilot and exception requests are reviewed.

Definition of done: three developers can create and deploy the pilot service through the same reviewed path, with fewer manual handoffs than the baseline and no added standing production credential.

Editorial judgment: Build a portal only after one golden path proves that it removes work without hiding risk. If you cannot name the owner, the allowed action, and the rollback path for a workflow, keep it manual while you repair those contracts.

FAQ

Do we need Backstage to start platform engineering?

No. A repository template and shared CI are usually the better first step when discoverability is not yet the problem.

Should a software template deploy to production?

No. Let the template create reviewed configuration; let a separate, approved delivery workflow deploy it with a short-lived identity.

What is the first metric to monitor?

Track manual handoffs from repository request to first deployment alongside the number of exceptions. Faster creation is not a success if the exception queue grows.