How to Stand Up a Developer Portal for Your Platform

A developer portal is one front door for services, docs, and self-service actions, backed by the software catalog.

Deploy a portal (Backstage, Port, or Cortex), point it at your catalog source, and expose scaffolding actions. Developers discover services and create new ones without leaving the portal.

Steps

• Pick a portal (Backstage self-hosted, or SaaS like Port or Cortex).
• Configure a catalog location that discovers catalog-info.yaml files.
• Wire scaffolder templates for self-service repo creation.
• Add auth so ownership maps to real teams.

Catalog location

catalog:
  locations:
    - type: github-discovery
      target: https://github.com/my-org/*/blob/-/catalog-info.yaml

Gotchas

• Discovery only finds entities that actually have a catalog-info.yaml; seed existing repos first.
• Keep the portal read-mostly at first; add write actions once ownership data is trustworthy.

Related guides