What Is an Internal Developer Platform (IDP) and What Should It Include?

An internal developer platform (IDP) is the self-service layer a platform team builds on top of existing infrastructure so application teams can provision environments, scaffold services, and ship code without filing tickets or learning every underlying tool. It is worth building when many teams repeatedly hit the same friction — slow environment setup, inconsistent service configuration, unclear ownership — and when you can staff a team to own the platform as a product. It is not worth building as a big-bang project before that demand is visible.

IDP vs. developer portal vs. software catalog

These three terms get used interchangeably, but they describe different layers:

A portal and a catalog are usually parts of an IDP, not synonyms for it. Backstage, for example, is described as an open source developer portal framework that centralizes a software catalog, unifies infrastructure tools, and helps teams ship code faster — that is the portal-and-catalog layer, which you then extend with templates and integrations to form a platform.

What an IDP typically includes

Service catalog

A registry of every service, library, and resource with ownership and metadata attached. This is the foundation: templates, docs, and on-call routing all reference it.

Software templates and scaffolding

Golden-path templates that generate a new service with the right repo structure, CI config, and catalog entry already in place. The goal is that a new service starts compliant by default rather than being fixed later.

Environment and infrastructure provisioning

Self-service creation of dev, staging, and test environments, usually by wrapping existing IaC or cloud APIs behind a simple request flow. This is where most ticket queues disappear.

CI/CD integration

Pipelines surfaced and triggered from the platform so teams don't context-switch between tools. The platform orchestrates; it rarely replaces the CI system.

Documentation

Docs living next to the code and the catalog entry, so they are found where work happens rather than in a separate wiki that drifts.

How platform teams build and operate an IDP

Platform engineering treats the IDP as a product with developers as customers:

1. Find the highest-friction repeated task. Interview teams and measure where lead time is lost — often environment setup or service bootstrapping.
2. Build one golden path end to end. Pick a single common service type and make its full lifecycle self-service.
3. Adopt a portal/catalog layer so the path is discoverable and ownership is visible. Backstage is one open source option here; commercial portals exist too.
4. Measure adoption and lead time, not just feature count. A path nobody uses is not a platform.
5. Expand only where demand repeats. Add the next template or integration when multiple teams ask for the same thing.

Common pitfalls

• Over-building before demand is clear. A large platform with few users is the classic failure. Start with one painful workflow and prove it.
• Building a portal with nothing behind it. A catalog that lists services but can't provision or scaffold anything is a directory, not a platform.
• Treating it as a side project. Without a dedicated owning team and a product mindset, the platform decays and teams route around it.
• Forcing adoption. Golden paths work when they are genuinely easier than the alternative; mandates without that ease breed shadow workflows.

Deciding whether to build one

Build an IDP when you have repeated cross-team friction, enough scale that a platform team pays for itself, and leadership willing to fund it as a product. If you mainly need visibility into what exists and who owns it, start with a software catalog and a portal interface; if you need to remove provisioning toil, add self-service templates and environment automation on top. Either way, the first deliverable should be one working golden path, not a platform roadmap.