Platform Engineering: Building Internal Developer Portals 2026

By /

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.

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-api

Why 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.

Platform engineering developer portal dashboard
The service catalog shows every service, its owner, dependencies, and health — in one place

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.yaml

The 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.

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: Before portal: 2 weeks. After: 1 hour. This is the single most impressive 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% 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.
Infrastructure automation workflow
Golden paths reduce time-to-first-deploy from weeks to hours

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.

Developer productivity metrics
Track adoption and developer satisfaction — a platform nobody uses has failed

Getting Started: The 30-Day Plan

  1. Week 1: Interview 10 developers. Ask what slows them down most. Identify the top 3 pain points.
  2. Week 2: Deploy Backstage, register 10 existing services in the catalog, and add GitHub + PagerDuty plugins.
  3. Week 3: Create one golden path template for the most common service type (probably a REST API with a database).
  4. 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, and expand based on what developers actually need.

Scroll to Top