Platform Engineering Developer Portal: Stop Making Developers File Tickets
Your developers want to deploy a new service. In most organizations, that means filing a Jira ticket for infrastructure, waiting 3 days for a Kubernetes namespace, filing another ticket for a database, waiting 2 more days, then configuring CI/CD, monitoring, and logging manually. Platform engineering developer portal replaces all of that with a self-service experience where developers click “Create New Service” and have a production-ready environment in 5 minutes.
What Platform Engineering Actually Is
Platform engineering is the discipline of building internal tools that make developers self-sufficient. It’s not about creating another layer of abstraction that developers have to fight — it’s about removing the toil that slows down delivery. Moreover, the best platform teams treat internal developers as their customers and build products for them, not bureaucratic processes around them.
The key insight is that most developer requests are variants of the same patterns: “I need a service with a database, a message queue, CI/CD, and monitoring.” A platform engineering team codifies these patterns into reusable templates (golden paths) that developers can instantiate with a few clicks. Consequently, the platform team stops being a bottleneck (processing tickets) and starts being a multiplier (building tools that serve everyone).
Spotify pioneered this with Backstage, their open-source developer portal that they built internally and then donated to the CNCF. Today, Backstage is the most widely adopted developer portal framework, used by teams from 50-person startups to enterprises with thousands of engineers.
Platform as a Product, Not a Project
Before any tooling, the mindset has to shift, and this is where most internal-platform efforts quietly fail. A project has an end date; a product has users, a roadmap, and a feedback loop. When leadership funds a platform as a one-time “build the portal” project, the team ships a v1, declares victory, and moves on — and within a quarter the catalog is stale, the templates have drifted from current standards, and developers route around the portal. The teams that succeed instead staff the platform like an internal SaaS company: they have a backlog driven by user interviews, they measure adoption, and they treat a feature nobody uses as a bug to be fixed, not a deliverable to be checked off.
This product framing also clarifies who the customer is. Your customer is the application developer, not the CTO and not the platform team’s own sense of architectural elegance. Therefore, when you debate whether to support a slightly nonstandard tech stack, the deciding question is not “is this clean?” but “will refusing it push real teams off the paved road?” Empathy here is a literal engineering input, because a platform that ignores its users’ actual workflows is, by definition, not done.
Building Your Portal with Backstage
Backstage provides three core capabilities: a service catalog (what services exist, who owns them, what they depend on), software templates (create new services from standardized templates), and a plugin ecosystem (integrate your existing tools into one interface).
# catalog-info.yaml — Register your service in the portal
# This file lives in YOUR repo, next to YOUR code
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: order-service
description: |
Processes customer orders, manages order lifecycle,
and publishes order events to Kafka.
annotations:
# Integrations — Backstage pulls data from these tools
github.com/project-slug: company/order-service
pagerduty.com/service-id: PSVC123
grafana/dashboard-selector: "order-service"
sonarqube.org/project-key: order-service
jenkins.io/job-full-name: order-service/main
tags:
- java
- spring-boot
- kafka
links:
- url: https://order-service.internal.company.com/swagger-ui
title: API Documentation
- url: https://grafana.internal/d/orders
title: Monitoring Dashboard
spec:
type: service
lifecycle: production
owner: team-commerce # Links to a Team entity
system: e-commerce-platform # Logical grouping
dependsOn:
- component:inventory-service
- component:payment-service
- resource:orders-database
- resource:orders-kafka-topic
providesApis:
- orders-api-v2
consumesApis:
- inventory-api
- payment-apiWhy the catalog matters: In a 200-service architecture, nobody can keep track of what exists, who owns it, and what it depends on. The catalog provides a live, searchable map of your entire system. Additionally, when someone is paged at 2 AM for the order-service, they can immediately see its dependencies, find the monitoring dashboard, and identify the owning team — all in one place.
The detail that makes this sustainable is that catalog-info.yaml lives in the service repository, not in a central registry someone has to remember to update. Backstage discovers it through a GitHub provider, so the catalog stays fresh as a side effect of normal development. This is the difference between a living map and the architecture diagram on a wiki that was last accurate two reorgs ago. The dependsOn graph is what turns the catalog from a directory into a tool: during an incident, you can walk the dependency edges to see that order-service is degraded because orders-database is, and you can walk them the other way to warn every team that consumes orders-api before you deploy a breaking change.
Golden Paths: Standardize Without Restricting
A golden path is a pre-built template that creates a new service with everything configured correctly: repository, CI/CD pipeline, Kubernetes manifests, database, monitoring dashboards, and alerting rules. The developer fills in a few fields (service name, team, tech stack) and the template does the rest.
# Software template — "Create New Microservice"
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: spring-boot-service
title: Spring Boot Microservice
description: |
Creates a production-ready Spring Boot service with:
- GitHub repository with branch protection
- CI/CD pipeline (GitHub Actions)
- Kubernetes deployment manifests
- PostgreSQL database (via Crossplane)
- Grafana dashboard + PagerDuty integration
- Sonar quality gate
spec:
owner: platform-team
type: service
parameters:
- title: Service Information
required: [name, description, owner]
properties:
name:
type: string
pattern: "^[a-z][a-z0-9-]*$"
description: Service name (lowercase, hyphens only)
description:
type: string
description: What does this service do?
owner:
type: string
ui:field: OwnerPicker # Dropdown of registered teams
database:
type: string
enum: [postgresql, mysql, none]
default: postgresql
messaging:
type: string
enum: [kafka, rabbitmq, none]
default: none
steps:
# 1. Generate code from template
- id: generate
name: Generate Service Code
action: fetch:template
input:
url: ./skeleton # Template repository
values:
name: ${{ parameters.name }}
owner: ${{ parameters.owner }}
# 2. Create GitHub repository
- id: publish
name: Create Repository
action: publish:github
input:
repoUrl: github.com?owner=company&repo=${{ parameters.name }}
description: ${{ parameters.description }}
defaultBranch: main
protectDefaultBranch: true
requireCodeOwnerReviews: true
# 3. Provision database if requested
- id: database
name: Provision Database
if: ${{ parameters.database != 'none' }}
action: crossplane:create
input:
apiVersion: database.company.io/v1
kind: PostgreSQLInstance
metadata:
name: ${{ parameters.name }}-db
spec:
size: small # 2 vCPU, 8GB RAM, 100GB storage
# 4. Register in Backstage catalog
- id: register
name: Register in Catalog
action: catalog:register
input:
repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
catalogInfoPath: /catalog-info.yamlThe crucial point: Golden paths are optional, not mandatory. Developers CAN deviate — but the golden path is so good that most don’t want to. This is the difference between platform engineering (paved roads) and infrastructure bureaucracy (gatekeeping). Furthermore, when 90% of services follow the golden path, operational support becomes dramatically easier because everything is consistent.
One subtlety in the template above carries most of the long-term value: the database step provisions infrastructure through Crossplane rather than a hand-written ticket. That means the platform exposes a single, opinionated abstraction — “I need a small PostgreSQL” — while the platform team retains control of what “small” maps to, which region it lands in, and which backup policy applies. Developers get speed; the organization keeps its guardrails. For the full picture of how that provisioning layer works, see our companion piece on GitOps with ArgoCD and Crossplane.
The Build-Versus-Buy Decision and the Spectrum of Tools
A frequent early misstep is assuming Backstage is the only option, then drowning in its operational cost. Backstage is powerful precisely because it is a framework: you write TypeScript plugins, run the backend, and own upgrades. For an organization with a dedicated platform team and dozens of services, that flexibility is worth it. For a smaller team, a managed alternative — Port, Cortex, or OpsLevel, among others — delivers a catalog and scorecards without the maintenance burden, and it is entirely legitimate to start there and migrate later if you outgrow it.
The honest framing is a spectrum, not a binary. On one end, buy a managed portal and accept its opinions; on the other, build deeply on Backstage and accept the staffing it requires. Most teams should buy or adopt the integration layer and build only the golden-path templates that encode their specific standards, because those templates are the part no vendor can write for you. Spending six months building a service catalog from scratch when three mature options exist is the kind of effort that feels productive and creates no developer value.
Platform Engineering Developer Portal: Measuring Success
A platform isn’t successful because it exists — it’s successful because developers use it voluntarily and ship faster. The metrics that matter:
- Time to first deploy for new services: Many teams report this dropping from a couple of weeks to roughly an hour after introducing golden paths. It is the single most legible metric to show leadership.
- Time to first deploy for new hires: How quickly can a new team member deploy a change? This measures how well your platform reduces onboarding friction.
- Golden path adoption rate: What percentage of new services use your templates? Below 70% generally means your templates don’t match what developers actually need — go talk to them.
- DORA metrics improvement: Deployment frequency, lead time for changes, MTTR, and change failure rate should all improve after platform adoption.
- Developer satisfaction: Survey your developers quarterly. Ask: “How easy is it to deploy a new service?” If scores aren’t improving, your platform has usability problems.
A word of caution on metrics: optimize for outcomes, not vanity. “Number of services in the catalog” looks impressive and means almost nothing, because it counts registration, not value. Adoption rate and satisfaction are harder to game because they measure whether developers choose the platform when no one is forcing them. The DORA framework is useful here precisely because it ties the platform back to delivery performance the business already cares about, rather than to internal activity the business never sees.
Common Mistakes to Avoid
Mistake 1: Building a portal nobody asked for. Start by talking to developers. What actually slows them down? Don’t assume — ask. You might discover that the biggest pain point isn’t service creation but database access, or not infrastructure at all but slow CI/CD pipelines.
Mistake 2: Making the portal mandatory and the only way. If developers can’t bypass the portal for edge cases, they’ll resent it. The portal should be the easiest way, not the only way.
Mistake 3: Building everything from scratch. Backstage exists. Crossplane exists. ArgoCD exists. Your job is to integrate and configure these tools for your organization, not to build a developer portal from zero.
Mistake 4: Platform team as gatekeepers. If the platform team must approve every service creation or infrastructure request, you’ve just moved the bottleneck. Self-service means self-service — with guardrails, not gates.
When a Developer Portal Is the Wrong Investment
It would be dishonest to pitch platform engineering as universally correct, so here is the counter-case. A portal is overhead that only pays off above a certain scale. If you run five services with three developers, a shared README and a good Makefile will serve you better than Backstage, and the engineer-months you would spend standing up a platform are better spent on the product. The toil that justifies a portal — dozens of near-identical service requests, an unmappable dependency graph, onboarding that takes weeks — simply does not exist yet at small scale.
There is also an organizational prerequisite that no tool can supply. A self-service platform assumes the underlying infrastructure is already automatable: if provisioning a database genuinely requires a human approval for compliance reasons, a portal cannot abstract that away, it can only hide it and frustrate everyone. Likewise, a platform built without a sustained team to maintain it decays into a liability faster than the manual process it replaced. So before you commit, ask honestly whether you have the scale to justify it, the automation to enable it, and the staffing to sustain it. If the answer to any of those is no, fix that first — building the portal will not fix it for you.
Getting Started: The 30-Day Plan
- Week 1: Interview 10 developers. Ask what slows them down most. Identify the top 3 pain points.
- Week 2: Deploy Backstage, register 10 existing services in the catalog, and add GitHub + PagerDuty plugins.
- Week 3: Create one golden path template for the most common service type (probably a REST API with a database).
- Week 4: Invite 5 developers to try the template. Observe them using it. Fix every friction point they encounter. Then open it to everyone.
Related Reading:
Resources:
In conclusion, platform engineering developer portal initiatives succeed when they’re built with empathy for developers and measured by developer outcomes. Start small, solve real pain points, buy what you can and build only the templates that encode your standards, and expand based on what developers actually need rather than what looks impressive on a roadmap.