Backstage Tutorial: Build an Internal Developer Portal Step by Step

Overview

Backstage is most useful when it gives engineers one dependable place to discover services, understand ownership, follow approved delivery paths, and find operational documentation. It should not attempt to replace every system used by a platform team. Source control, CI/CD, infrastructure, observability, incident management, and cloud consoles can remain separate while Backstage presents the context and links people need to work effectively.

Before installing plugins or designing a complex internal developer platform, define the first workflow you want to improve. A sensible starting point is service discovery: an engineer can search for a component, see its owner and lifecycle, open its repository, read its documentation, and find its deployment or monitoring links. Once that information is reliable, add software templates for repeatable creation of new services or infrastructure.

Use the following assumptions for an initial implementation:

• Your teams already have source repositories and a preferred CI/CD workflow.
• Each registered component can have a clear owner, even if ownership is represented by a team rather than an individual.
• The platform team can establish a small set of metadata conventions and review them with service owners.
• Backstage will be treated as a product with users, support expectations, and a maintenance backlog.

The goal is a narrow, trusted portal. A smaller catalog with accurate metadata is more valuable than a broad catalog filled with stale records.

What to track

1. Catalog coverage and ownership

Start with a catalog model that answers basic operational questions. For every service or library, track its name, description, repository, lifecycle, system or domain, owner, and links to relevant documentation and operational tools. Keep ownership explicit. An owner should be a team that can respond to questions and maintain the component, not merely the person who created it.

A minimal catalog entity can look like this:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payments-api
  description: Service responsible for payment requests
  annotations:
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: production
  owner: team-payments
  system: commerce

Agree on naming and allowed values before registering hundreds of components. For example, decide whether lifecycle values will be limited to experimental, production, and deprecated, and document who can create or change team records. Consistency makes catalog searches and future automation more useful.

2. Software templates

Backstage software templates should encode a path your organization is prepared to support. A useful template can collect a service name, owner, repository location, runtime choice, and deployment environment. It can then create a repository, add baseline files, register the component, and invoke the established CI/CD process.

Do not begin by creating a template for every possible technology. Choose one common service pattern and make its defaults safe. Include a README, ownership metadata, health-check expectations, a basic test workflow, and links for documentation and observability where those integrations already exist. A template that creates files without a supported operating model only moves complexity to the team that uses it.

3. Documentation and technical context

Connect documentation to the repository that owns it. A service page should help a new contributor answer: What does this component do? Who owns it? How is it deployed? What dependencies does it have? Where are logs and dashboards located? What is the first troubleshooting step?

Keep documentation close to code when possible so changes can be reviewed with the component. A short runbook is better than a large page nobody updates. For incident procedures, use a consistent structure such as symptoms, impact, checks, mitigation, escalation, and recovery. The SRE runbook template provides a useful companion structure.

4. Authentication, permissions, and sensitive data

Authentication establishes who can use the portal; authorization determines what they may change or view. Connect Backstage to the identity provider already used by your organization, then map users to teams and groups that match catalog ownership. Keep administrative permissions narrow and separate catalog editing from template administration where practical.

Never use the catalog as a place to store credentials, tokens, private keys, or unrestricted operational secrets. Store references to protected systems rather than secret values. Review template actions and plugin permissions before enabling them, especially when they can create repositories, modify infrastructure, or trigger deployments.

5. Platform health and adoption signals

Track signals that show whether the portal is useful and trustworthy. Reasonable measures include:

• Percentage of in-scope services with an owner, repository, lifecycle, and operational links.
• Number of catalog records with stale or missing metadata.
• Template runs that complete successfully, fail, or require manual correction.
• Time between a new repository or service being created and its catalog registration.
• Documentation or runbook review completion for critical services.
• Feedback themes from engineers, service owners, and incident responders.

These are diagnostic signals, not targets to optimize blindly. High page traffic can coexist with poor data quality, while a lower number of visits may be acceptable if the portal is used during important workflows.

Cadence and checkpoints

Run the internal developer portal as a recurring operating process. A monthly review is usually frequent enough for a small portal; a larger or fast-changing platform may need more frequent checks for failed integrations. A quarterly review is useful for architectural decisions and adoption patterns.

Monthly review

1. Check failed catalog processing, broken repository links, and template errors.
2. Review components with missing owners, invalid lifecycle values, or outdated operational links.
3. Sample several service pages with their owners and confirm that the displayed information is still useful.
4. Review support requests and group them into documentation, reliability, workflow, or access problems.
5. Remove obsolete records only after confirming that the underlying service has been retired or renamed.

Quarterly review

1. Ask whether the portal is still solving the original workflow problem.
2. Compare portal usage and feedback with the effort required to maintain integrations.
3. Review templates for outdated dependencies, unsupported deployment paths, or unnecessary prompts.
4. Audit permissions, administrative access, and actions that can affect repositories or infrastructure.
5. Choose one or two improvements for the next quarter rather than expanding every integration request.

Record each review in a lightweight changelog. Note what was checked, what was corrected, which owners were contacted, and what remains unresolved. This creates an operating history and makes future maintenance less dependent on individual memory.

How to interpret changes

A rise in catalog records is not automatically progress. If coverage grows while ownership and documentation quality fall, the registration process may be encouraging quantity over usefulness. Investigate whether records are being created automatically without an accountable owner or whether teams do not understand the metadata requirements.

Repeated template failures usually indicate a product design problem rather than isolated user error. Look for unstable dependencies, unclear inputs, permissions that are too broad or too restrictive, and steps that require undocumented manual work. A template should fail early with a clear explanation and should leave a recoverable result when possible.

Stale documentation can mean one of several things: the page is hard to find, ownership is unclear, the review process is inconvenient, or the documentation is not needed in the form provided. Ask service owners which operational questions they actually receive, then improve the highest-value content first.

When teams request many plugins, distinguish a repeated organizational need from a one-off preference. Prefer links and small metadata additions before introducing a new integration. Every plugin creates upgrade, permission, testing, and support work. A maintainable internal developer platform has a clear boundary around what it owns.

For services deployed to Kubernetes, the portal should complement deployment standards rather than conceal them. Use the Kubernetes deployment best practices checklist to review the operational expectations behind a service template. If the portal links to CI/CD or GitOps workflows, document which system is authoritative and how a change moves from source to production. The comparison in GitOps vs. CI/CD can help frame that decision.

When to revisit

Revisit this Backstage implementation monthly for data quality and reliability, and quarterly for scope and architecture. Update it sooner when your identity provider changes, repository structure is reorganized, deployment ownership moves, a template creates an unsupported service, or a security review identifies an excessive permission.

Use this practical checklist at the next review:

• Choose the five most important service pages and verify their owners, repositories, lifecycle values, documentation, and operational links.
• Run each supported software template in a non-production test path and record the result.
• Inspect catalog and application logs for failed processing or integration errors.
• Ask two engineers who are not part of the platform team to complete a common task and note where they hesitate.
• Review administrator and template permissions, including access to repository and deployment actions.
• Prioritize one reliability fix, one data-quality fix, and one user-experience improvement.

Expand only after the first workflow is trusted. A portal that reliably answers ownership and service-context questions is a strong foundation for templates, documentation, scorecards, and additional cloud-native tooling. Keep the architecture understandable, publish the maintenance rules, and treat every new integration as a long-term commitment rather than a feature to collect.