The Problem Backstage and Port Both Solve
Engineering teams above 50-ish people hit the same wall: nobody knows what services exist, who owns them, or how to deploy a new one without bothering three different teams. An internal developer platform (IDP) gives engineers a single place to discover services, provision infrastructure, and follow organizational standards without filing tickets.
Backstage (open-source, originally from Spotify) and Port (commercial SaaS) are the two most common choices right now. They solve the same problem but with fundamentally different philosophies. Backstage gives you a framework and expects you to build your platform. Port gives you a product and expects you to configure it.
Backstage Architecture and What You're Signing Up For
Backstage is a React frontend backed by a Node.js server, with a PostgreSQL database for the software catalog. It uses a plugin architecture — almost everything is a plugin, including the core software catalog. Spotify open-sourced it in 2020, and it's now a CNCF Incubating project.
Here's what the documentation downplays: running Backstage in production is a significant engineering investment. You're not installing an application — you're forking a framework and maintaining it. The upgrade path involves rebasing your customizations on top of new releases, and breaking changes between minor versions aren't uncommon.
The software catalog is populated through YAML files that live alongside your code. Each service has a catalog-info.yaml that declares its metadata:
# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payment-service
description: Handles payment processing and invoicing
tags:
- java
- grpc
annotations:
github.com/project-slug: myorg/payment-service
pagerduty.com/service-id: P1234XYZ
grafana/dashboard-selector: "payment-*"
spec:
type: service
lifecycle: production
owner: team-payments
system: billing
dependsOn:
- component:user-service
- resource:payments-db
providesApis:
- payment-apiPlugin Development
Backstage's strength is its plugin ecosystem. There are plugins for PagerDuty, Grafana, ArgoCD, GitHub Actions, Kubernetes, and dozens more. Community plugins vary in quality — some are well-maintained, others haven't been updated in months. For anything beyond the most common integrations, you'll write your own plugin.
Writing a Backstage plugin isn't trivial. You need familiarity with React, Material UI, and Backstage's internal APIs (which change). A basic plugin that shows data from an external API takes a competent frontend developer about a week. A plugin with scaffolder integration (for creating new services from templates) takes two to three weeks.
Port's Approach: Configuration Over Code
Port takes a different tack. Instead of a framework you extend with code, it's a SaaS product you configure through its web interface and REST API. You define a data model (they call it a "blueprint"), set up integrations that sync data from your existing tools, and build self-service actions that trigger workflows.
The data model is the core concept. A blueprint defines an entity type — service, cluster, environment, deployment — with typed properties and relations. It's similar to Backstage's catalog model, but it lives in Port's database instead of in YAML files alongside your code.
# Port blueprint definition (via API)
{
"identifier": "microservice",
"title": "Microservice",
"schema": {
"properties": {
"language": {
"type": "string",
"enum": ["python", "java", "go", "typescript"]
},
"tier": {
"type": "string",
"enum": ["critical", "standard", "experimental"]
},
"oncall_team": {
"type": "string"
},
"last_deploy": {
"type": "string",
"format": "date-time"
},
"health_status": {
"type": "string",
"enum": ["healthy", "degraded", "down"]
}
}
},
"relations": {
"environment": {
"target": "environment",
"required": false
},
"cluster": {
"target": "k8s_cluster",
"required": false
}
}
}Self-Service Actions
Both platforms support self-service actions — letting developers do things like "create a new microservice" or "spin up a staging environment" without filing a ticket. Backstage does this through its Software Templates (scaffolder) system, which uses YAML-defined templates with steps that call out to various providers. Port does it through Actions, which can trigger GitHub Actions, GitLab CI, webhooks, or its own automation engine.
Port's actions are faster to set up because you define them through the UI. Backstage templates are more flexible because they're code. Pick based on your team's comfort level — if you've got strong frontend engineers who like building things, Backstage wins. If your platform team is small and operations-focused, Port gets you to value faster.
Decision Criteria That Actually Matter
Team size is the biggest factor. Below 3 platform engineers, don't pick Backstage. You'll spend all your time maintaining the platform instead of building features on it. Port or a simpler alternative gets you further with less staff.
Above 5 platform engineers, Backstage becomes viable. The customization ceiling is much higher, and the total cost of ownership can be lower than Port's per-seat pricing at scale (Port charges per developer seat, Backstage is free to run but expensive to staff).
Data model complexity matters too. If your organization has a straightforward service catalog — services, APIs, teams — both work fine. If you need to model complex relationships like "this service depends on that queue which is provisioned in this cluster managed by that team in this cost center," Port's flexible blueprint system handles this out of the box while Backstage requires custom catalog entity kinds and processors.
Integration depth is where Backstage often wins. Because you're writing code, you can build integrations that do exactly what you need. Port's integrations are config-driven, which is faster but constrained to what the integration supports. Custom integrations in Port go through their API, which adds a layer of indirection.
Migration Considerations
If you're moving from a spreadsheet or wiki to either platform, start with the software catalog. Don't try to build self-service actions, scorecards, and dashboards simultaneously. Get your services registered, get ownership assigned, and let developers build the habit of checking the catalog before asking in Slack. That foundation makes everything else easier.
Both platforms support importing from existing sources — GitHub repos, Kubernetes clusters, cloud provider APIs. Lean on automated discovery rather than asking teams to register services manually. The manual approach creates a stale catalog within months.
Scorecards and Standards Enforcement
Both platforms support scorecards — automated checks that measure how well services conform to organizational standards. Does the service have an owner? Does it have a runbook? Is its dependency declaration up to date? Are its SLOs defined? Scorecards turn organizational standards from aspirational documents into measurable compliance.
Port's scorecards are built into the product — you define rules through the UI and they evaluate automatically against your entity data. You can weight rules differently (a missing production runbook is more severe than a missing description) and track compliance trends over time. Backstage requires the tech-insights plugin for similar functionality, which is less mature and requires more setup but offers deeper customization.
The biggest risk with scorecards is gaming. If a service gets a green checkmark for having a runbook, teams will create empty runbooks to satisfy the check. Effective scorecards check for substance, not existence — a runbook should contain actual procedures, an owner should be a real team in your identity provider, SLOs should have active alerting. The more you can validate through automated checks rather than boolean "exists/doesn't exist" flags, the more useful the scorecard becomes.
Operational Maturity
Scorecards work best when they map to an explicit maturity model. Level 1: service is registered with an owner. Level 2: service has monitoring and a runbook. Level 3: service has defined SLOs with error budgets. Level 4: service participates in automated incident response. Teams can see where their services stand and what they need to do to level up, turning platform adoption from a compliance exercise into a progressive improvement path.
This maturity model approach also helps with prioritization. You don't need every service at Level 4 — critical production services should target Level 3-4, while internal tools might be fine at Level 1-2. The platform team sets the expectations per service tier, and scorecards enforce them automatically.