Portal vs Platform: Why Your IDP Is Just Links

Last month I watched a developer spend three days getting a PostgreSQL database. The company had a beautiful internal developer portal - Backstage, fully themed, comprehensive service catalog, scorecards showing tech debt metrics. The developer found the “Database Provisioning” page in under 30 seconds. Then he read the instructions: file a Jira ticket with the DBA team, wait for triage, attend a 15-minute review meeting to justify the request, and receive credentials via a separate ticket once provisioning completed. Three to five business days, assuming no holidays or sick leave on the DBA team.

The portal worked perfectly. The developer knew exactly where to go and what to do. And yet the outcome was identical to not having a portal at all - the same tickets, the same meetings, the same waiting.

That’s the portal-versus-platform distinction that trips up most organizations. A portal indexes things: it aggregates links, surfaces documentation, shows who owns what. A platform does things: it provisions infrastructure, creates repositories, grants access. The portal tells you how to request a database. The platform gives you a database.

The difference matters because it determines whether your internal developer platform actually reduces toil or just makes toil easier to find. Self-service actions are what transform a directory into a platform. Without them, you’ve built a prettier wiki.

The Portal Maturity Model

Most internal developer portals evolve through predictable stages. Understanding where you are helps clarify where to invest next - and where most organizations get stuck.

Self-Service Action Design

The difference between a good self-service action and a frustrating one often comes down to design decisions that seem minor but compound. A database provisioning action that takes 30 seconds to fill out and 15 minutes to complete feels magical. The same action with a confusing form, unclear outcomes, and no progress visibility feels like a different kind of ticket system.

Anatomy of a Good Action

A well-designed action has clear structure: identity (what it is), inputs (what the user provides), workflow (what happens), and outputs (what the user gets back). Here’s what that looks like for database provisioning:

# Backstage scaffolder action for PostgreSQL provisioning
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: provision-postgresql-database
  title: Create PostgreSQL Database
  description: Provision a new PostgreSQL database with configured access
  tags: ["postgresql", "database", "self-service"]
spec:
  owner: platform-data-team
  type: database

  parameters:
    - title: Database Configuration
      required: [name, environment, size]
      properties:
        name:
          title: Database Name
          type: string
          pattern: "^[a-z][a-z0-9-]{2,30}$"
          description: Lowercase letters, numbers, hyphens. 3-31 chars.
        environment:
          title: Environment
          type: string
          enum: [dev, staging, production]
          default: dev
        size:
          title: Instance Size
          type: string
          enum: [small, medium, large]
          enumNames:
            - Small (2 vCPU, 8GB) - $50/mo
            - Medium (4 vCPU, 16GB) - $150/mo
            - Large (8 vCPU, 32GB) - $400/mo
          default: small

  steps:
    - id: create-terraform-pr
      name: Create Infrastructure PR
      action: publish:github:pull-request
      input:
        repoUrl: github.com?repo=infrastructure&owner=myorg
        branchName: db-${{ parameters.name }}
        title: "Provision database: ${{ parameters.name }}"

    - id: wait-for-apply
      name: Apply Infrastructure
      action: terraform:wait-for-apply
      input:
        prUrl: ${{ steps.create-terraform-pr.output.remoteUrl }}

    - id: store-credentials
      name: Store Credentials
      action: vault:create-secret
      input:
        path: databases/${{ parameters.name }}

The YAML is straightforward, but the design decisions matter. Notice the sensible defaults (dev environment, small size), the clear cost indication in the enum labels, and the validation pattern that prevents naming mistakes before submission. For more on Backstage scaffolder actions, see the Backstage documentation on software templates.

Action Design Guidelines

Workflow Automation

Self-service actions rarely involve a single step. Provisioning a new service might mean creating a repository, generating infrastructure-as-code, waiting for Terraform to apply, storing credentials in Vault, and registering the service in the catalog. Each step can fail. Each step depends on outputs from previous steps. And if something fails halfway through, you need a plan for the orphaned resources.

This is workflow orchestration - coordinating multi-step processes with proper error handling, progress visibility, and rollback support.

The Anatomy of a Multi-Step Workflow

Consider what happens when a developer requests a new service. The portal validates their inputs and permissions, creates a repository from a template, generates a Terraform PR for the service’s infrastructure, waits for approval (or auto-approves for non-production), applies the Terraform changes, stores the resulting credentials, and notifies the developer. That’s seven steps with dependencies between them.

The sequence diagram shows the happy path, but real workflows need to handle failures at every step. What if the repository creation succeeds but the Terraform PR fails? What if the apply times out? What if credential storage fails after infrastructure is already provisioned?

Designing for Failure

Each workflow step needs three things: a clear action, defined failure behavior, and (where appropriate) a rollback action.

Failure behaviors fall into a few categories. Some failures should abort the entire workflow - if validation fails, there’s no point continuing. Some should retry - transient API errors often resolve on the second attempt. Some should skip - failing to send a notification shouldn’t block an otherwise successful provisioning. And some should trigger manual intervention - edge cases that automation can’t handle.

Rollback steps clean up resources created by earlier steps when a later step fails. If you create a repository in step 2 but the infrastructure PR fails in step 3, the rollback should delete that repository. Without rollback, failed workflows leave orphaned resources that accumulate over time - repositories nobody uses, partial infrastructure deployments, dangling secrets.

The key insight is that non-critical steps should fail gracefully. Registering a service in the catalog is nice to have, but if it fails, the service still exists and works. Mark these steps as “skip on failure” so they don’t block the overall workflow.

Approval Workflows

Approvals are where self-service platforms often regress into ticket systems. The instinct is understandable - production changes are risky, expensive resources need oversight, compliance requires audit trails. But if every request routes through a manual approval queue, you’ve just built Jira with a different skin.

The solution is policy-based approval routing: define rules that auto-approve low-risk requests while routing high-risk ones to the right approvers. Most requests should flow through automatically. Approvals become the exception, not the rule.

Approval Policy Dimensions

Different situations warrant different approval requirements. Here are the dimensions that typically matter:

These dimensions combine. A production database deletion during change freeze might require team lead approval and security review and change freeze exception - three separate approvers. A dev environment S3 bucket during business hours? Instant auto-approval.

In Backstage, you’d implement these rules through a custom approval plugin or integrate with Open Policy Agent (OPA) for policy-as-code. The scaffolder evaluates the policy before executing steps, routing to the appropriate approval workflow or proceeding automatically based on the policy decision.

Making Approvals Fast

Even when manual approval is required, it shouldn’t be slow. A few practices help:

Integration Patterns

A self-service platform doesn’t exist in isolation. It needs to talk to your Git provider to create repositories, your infrastructure tooling to provision resources, your secrets manager to store credentials, your observability stack to set up monitoring, and your communication tools to send notifications. The integration layer is where the platform connects to reality.

Integration Categories

Most platforms need integrations across five categories:

The Adapter Pattern

The key architectural insight is that actions shouldn’t know which specific provider they’re using. A “create repository” step should work whether you use GitHub, GitLab, or Bitbucket. This means designing integrations as adapters with standard interfaces.

Each adapter declares its capabilities (what actions it can perform), implements a standard execution interface, and handles provider-specific authentication. The platform’s action definitions reference abstract capabilities like createRepository(name, template, visibility) and createPullRequest(repo, branch, title, body) rather than provider-specific APIs. The GitHub adapter implements these by calling the GitHub API; the GitLab adapter calls the GitLab API. The action definition doesn’t know or care which one runs.

This abstraction pays off when you need to swap providers. Moving from GitHub to GitLab, or from Terraform Cloud to Atlantis, becomes a configuration change rather than a rewrite of every action that touches those systems.

Building a platform is an investment - in tooling, integrations, and ongoing maintenance. Justifying that investment requires metrics that show the platform is actually delivering value. The trap is measuring what’s easy (action count) instead of what matters (developer productivity).

Metric Categories

Interpreting Metric Combinations

Metrics are most useful in combination. Here’s what different patterns indicate:

The Metrics That Matter Most

If you can only track a few things, focus on these:

The first two metrics (time to provision) are the most compelling for stakeholders. “We reduced database provisioning from 3-5 days to 15 minutes” is a story everyone understands. The last two metrics (ticket reduction, auto-approval rate) show operational efficiency - the platform team can do more with less manual intervention.

Conclusion

The distinction between portal and platform comes down to one question: what happens after a developer finds what they need? In a portal, they read documentation and file tickets. In a platform, they click a button and get resources.

That developer waiting three days for a database? In a real platform, they’d have filled out a form, seen a preview of what would be created, clicked submit, and had credentials in their hands within 15 minutes. No tickets. No meetings. No waiting for another team’s availability.

Getting there requires intentional design. Actions need obvious outcomes and sensible defaults. Approval policies should auto-approve aggressively and only route exceptions to humans. Workflow orchestration must handle failures gracefully and clean up after itself. Integrations should abstract away provider specifics so you can evolve the underlying systems without rewriting everything.

Level 4 platform maturity isn’t cheap. It requires investment in tooling, integration work, and ongoing maintenance. But the returns are proportional: developer productivity multiplied across the organization, platform team leverage instead of ticket-by-ticket toil, and the compounding benefits of standardization and automation.