Backstage.io is the most widely deployed internal developer portal in enterprise engineering — but a poorly configured Backstage becomes a maintenance burden rather than a productivity accelerator. The difference is governance: a clear plugin strategy, a maintained software catalogue, and an ownership model that keeps the portal alive beyond the initial deployment sprint. This enterprise setup guide covers the architecture decisions, plugin ecosystem, catalogue management, and governance model that make Backstage succeed at scale.
Backstage Enterprise Architecture
Essential Plugin Stack for Enterprise
| Plugin | Function | Source | Priority |
|---|---|---|---|
| Software Catalogue | Central service registry — all your services, APIs, libraries, teams | Core (built-in) | Must Have |
| TechDocs | Docs-as-code — renders markdown docs from repos alongside service catalogue | Core (built-in) | Must Have |
| Scaffolder | Self-service infrastructure templates — create new services via guided wizard | Core (built-in) | Must Have |
| GitHub/GitLab Actions | CI/CD status per service in catalogue | Community | High |
| PagerDuty | On-call schedule and incident history per service | Community | High |
| Kubernetes | Live pod status and deployments per service in catalogue | Community | High if using K8s |
| Cost Insights | Cloud cost per team and service | Community (Spotify) | Medium |
| Dynatrace / Datadog | Observability metrics per service in catalogue | Community | Medium |
Software Catalogue Setup
The software catalogue is Backstage's core value — but it only works if it is accurate and complete. The most common Backstage failure mode: incomplete catalogue that developers don't trust, so they stop using the portal.
- One file per repository — committed to repo root
- Minimum fields: kind, metadata.name, metadata.tags, spec.owner, spec.lifecycle
- Add links: runbook URL, dashboard URL, on-call rotation
- Auto-discover via GitHub/GitLab integration — no manual registration
- Every entity in the catalogue must have a spec.owner — a Group entity (team)
- Groups sync from GitHub teams, Okta groups, or LDAP
- Orphaned entities (no owner) surface in CoE dashboard — mandate resolution
Backstage Governance Model
Add a CI check that fails if a new service repository doesn't have a valid catalog-info.yaml. Make catalogue registration a deploy gate — not an optional afterthought. Use Backstage's Scaffolder templates to auto-generate catalog-info.yaml when creating new services. This ensures the catalogue stays current as your service portfolio grows without requiring manual updates. Connect to your CI/CD pipeline.
Run a quarterly audit: services with no owner, services with no documentation, services marked production but with no monitoring links. Assign remediation tickets in your sprint backlog. Track catalogue completeness score over time — make it a visible engineering quality metric in your team dashboards. A 90%+ completeness score is the threshold at which developers begin trusting and using the catalogue for daily work.
Our DevOps and digital transformation teams implement Backstage for enterprise organisations — deployment, plugin configuration, catalogue population, and governance model. Book a free advisory session.