Internal Developer Platform Best Practices For Modern Software Teams
by GainHQ Editorial Team | May 31, 2026 | Software Development Insights | Editorial policy
Table of Contents
- What is an internal developer platform?
- Internal developer platform vs internal developer portal
- What an internal developer platform includes
- What does an internal developer platform look like in practice?
- Benefits of an internal developer platform, and the trade-offs
- Internal developer platform vs DevOps vs platform engineering
- How to build an internal developer platform
- Build, adopt open source or buy?
- How to measure whether your internal developer platform is working
- Common internal developer platform challenges and how to avoid them
- Do you need an internal developer platform?
- How GainHQ can help
An internal developer platform (IDP) is a set of self-service tools, templates and automated workflows that a platform team builds so developers can create, deploy and run software without filing tickets or learning every piece of infrastructure underneath. The best IDPs are treated as internal products: they start small, solve the most painful developer tasks first, and grow based on feedback from the teams that use them.
What is an internal developer platform?
An internal developer platform is the shared layer between application teams and the infrastructure they depend on. Instead of each team assembling its own CI/CD pipeline, cloud resources, secrets handling and monitoring, the platform offers these as ready-made, self-service capabilities with sensible defaults.
The Cloud Native Computing Foundation's Platforms White Paper defines a platform as "an integrated collection of capabilities" that is "defined and presented according to the needs of the platform's users." Its stated purpose is to reduce the cognitive load on product teams and so speed up product development and delivery.
Three ideas sit at the centre of most definitions:
- Self-service. Developers get what they need (a new service, a database, a test environment) through a portal, CLI, API or template, without waiting on another team.
- Golden paths. The 2024 DORA report describes golden paths as "highly-automated, self-service workflows" that abstract away the complexity of building and delivering software "such that the developer only needs to worry about their code." Its examples include new application provisioning, database provisioning, schema management, test execution and DNS management.
- A platform team that runs it as a product. Team Topologies describes platform teams as teams that offer internal services to speed up stream-aligned (product) teams, and recommends a "thinnest viable platform" that provides "just enough capability without unnecessary complexity."
An internal developer platform is also different from internal business tools such as admin panels or operations dashboards. Those serve staff across the company; if that is what you need, see our guide to custom internal tools.
Internal developer platform vs internal developer portal
An internal developer portal is the user interface of a platform; the internal developer platform is everything behind it. A portal lets developers discover services, read documentation and trigger self-service actions. The platform provides the automation, infrastructure and policies those actions run on.
Gartner's market page defines internal developer portals as tools that enable "self-service discovery, automation and access to reusable components, tools, platform services and knowledge assets." Its mandatory features are a configurable dashboard, broad integrations across the toolchain, and software catalogs. The CNCF white paper treats portals as one of several interfaces to a platform, alongside APIs, CLIs, IDE plugins and documentation.
| Internal developer portal | Internal developer platform | |
|---|---|---|
| What it is | A front door: web UI with catalog, docs and self-service actions | The full set of capabilities: pipelines, environments, infrastructure, security, observability |
| Main user question | "What exists, who owns it, and how do I start?" | "How does my code get built, deployed, secured and run?" |
| Typical contents | Software catalog, service ownership, scorecards, templates, TechDocs | CI/CD, infrastructure provisioning, environment management, secrets, policy, monitoring |
| Can it exist alone? | Yes, as a catalog and documentation hub, but self-service actions need automation behind them | Yes, through CLIs, APIs and templates without a portal |
| Open source example | Backstage, "an open source framework for building developer portals" | Assembled from CI/CD, infrastructure-as-code and orchestration tools, often with Backstage on top |
Which features should a developer portal contain? Start with a software catalog (every service, its owner, its dependencies and its docs), software templates for new projects, and documentation stored alongside code. Backstage's core features are exactly these three: Software Catalog, Software Templates and TechDocs, extended by plugins. Scorecards and self-service actions come next.
What an internal developer platform includes
An IDP includes whatever capabilities your product teams repeatedly need and should not have to build themselves. The CNCF white paper lists the capabilities a platform may offer; few organisations need all of them on day one.
| Capability area (CNCF) | What a developer sees | Example of the self-service action |
|---|---|---|
| Web portals and APIs for provisioning | A catalog and "create" buttons, or an API/CLI | Request a new service from a template |
| Golden path templates and docs | Starter repositories with build, test, deploy and monitoring wired in | Scaffold a service that passes security checks from the first commit |
| Build and test automation | Shared CI pipelines | Unit and integration tests run without the team owning the runners |
| Delivery and verification automation | Standard deployment pipelines | Promote a build from staging to production |
| Development environments | On-demand environments | Spin up a preview environment for a pull request |
| Application observability | Logs, metrics and traces by default | Dashboards created when the service is created |
| Infrastructure, data and messaging services | Managed compute, databases, queues | Provision a database with backups configured |
| Identity, secrets and security services | Built-in access control and secret storage | Rotate a credential without a ticket |
| Artifact storage | Shared registries | Publish a container image or package |
Two design choices shape how these capabilities feel to developers. First, interfaces: the CNCF paper recommends meeting users where they are through "a combination of GUIs, APIs, command-line tools, IDEs, and portals." Second, composability: its list of platform attributes includes "optional and composable", meaning teams can adopt parts of the platform rather than all of it, and "secure by default."
Repository strategy also affects what golden paths look like. A template that scaffolds a new service works differently in a single shared repository than across many; our monorepo vs polyrepo guide covers that trade-off.
What does an internal developer platform look like in practice?
In practice, a developer opens a portal or runs a CLI command, picks a template, answers a few questions, and gets a working, deployable service with the organisation's standards already applied. The example below is illustrative only (not GainHQ client data) and shows a typical "new service" golden path.
| Step | Without a platform (illustrative) | With a golden path (illustrative) |
|---|---|---|
| 1. Create the service | Copy an old repo, remove what is not needed | Choose "Backend service" template in the portal |
| 2. Set up CI/CD | Write a pipeline, ask DevOps to review it | Pipeline included in the template |
| 3. Get infrastructure | Raise a ticket for a database and environment | Select "needs PostgreSQL"; the platform provisions it |
| 4. Secrets and access | Ask security for credentials | Secrets injected from the shared secret store |
| 5. Observability | Add logging and dashboards later, if remembered | Logs, metrics and alerts created by default |
| 6. Ownership and docs | Update a wiki page | Service registered in the catalog with owner and docs |
Benefits of an internal developer platform, and the trade-offs
The strongest independent evidence comes from the 2024 DORA Accelerate State of DevOps report, which tested the relationship between using an internal developer platform and delivery outcomes. It found real gains and real costs. DORA left the definition of an IDP broad, and 89% of its respondents said they were using one, so treat these as survey-based associations rather than guarantees.
| DORA 2024 finding (platform users vs non-users) | Change |
|---|---|
| Individual productivity | 8% higher |
| Team performance | 10% higher |
| Organisational performance | 6% higher |
| Software delivery throughput | About 8% lower |
| Change stability | 14% lower |
| Productivity when developers can complete tasks without an enabling team (developer independence) | 5% higher, at both individual and team level |
| Team productivity with a dedicated platform team | 6% higher (negligible for individuals) |
| Throughput when developers must use the platform exclusively for the whole lifecycle | 6% lower |
Source: DORA 2024 report, Platform engineering chapter.
What this means in plain terms:
- The benefits are real but moderate. Developers and teams are more productive, and organisations perform better, when a platform is in place.
- More machinery can slow changes down. DORA's hypothesis for lower throughput is the extra handoffs between systems (testing, security checks, deployment, monitoring) that each change passes through.
- Platforms can let bad changes through faster. Lower change stability means more failed changes and rework. DORA also found that instability combined with a platform was linked to higher burnout.
- Results dip before they improve. DORA saw early gains, then a decrease and recovery as platforms aged, the familiar "j-curve" of transformation work.
- Self-service matters more than mandates. Developer independence lifted productivity; forcing exclusive use of the platform reduced throughput.
Internal developer platform vs DevOps vs platform engineering
DevOps is a culture and set of practices that brings development and operations together; platform engineering is the discipline of building internal platforms; an internal developer platform is the product that discipline delivers. DORA describes platform engineering as "a sociotechnical discipline" and argues it is a way to scale practices such as "you build it, you run it" across an organisation, because "once a capability is in the platform, teams essentially get it for free." For how the two disciplines compare in practice, see our guide to DevOps vs platform engineering.
A platform does not remove the need for DevOps skills. It moves repeated operational work into a shared, maintained product so that product teams can spend more time on features. Where that platform team sits in your organisation matters; our guide to engineering team structure explains how platform, product and enabling teams fit together.
How to build an internal developer platform
Build an internal developer platform the way you would build any product: find the users' biggest pain, ship the smallest useful thing, measure whether it helps, and iterate. The CNCF white paper's main warnings are that platform teams must develop the platform together with users, choose priorities and first partner teams carefully, and show leadership the platform's impact on value streams.
- Find the friction. Interview developers and review where work waits: environment requests, pipeline setup, access tickets, onboarding. Pick the one or two tasks that cost the most time across teams.
- Define a thinnest viable platform. Following Team Topologies, start with just enough capability to remove that friction. Often the first version is one golden path template plus documentation.
- Choose a partner team. Build the first golden path with one product team that has the problem now. Their adoption is your first real test.
- Decide what to build, adopt or buy (see the next section). Most platforms are assembled from existing tools rather than written from scratch.
- Make self-service the default, not a mandate. DORA's data favours developer independence over exclusive-use rules. Keep escape hatches for teams with unusual needs.
- Collect feedback continuously. DORA found that not collecting feedback on the platform has a negative impact. Common methods it lists are informal conversations and issue trackers, followed by co-development, surveys, telemetry and interviews.
- Measure and expand. Add the next capability only when the first one is used and measured.
Use the CNCF Platform Engineering Maturity Model to check where you are and what the next step looks like:
| Aspect | Provisional | Operational | Scalable | Optimizing |
|---|---|---|---|---|
| Investment | Voluntary or temporary | Dedicated team | As product | Enabled ecosystem |
| Adoption | Erratic | Extrinsic push | Intrinsic pull | Participatory |
| Interfaces | Custom processes | Standard tooling | Self-service solutions | Integrated services |
| Operations | By request | Centrally tracked | Centrally enabled | Managed services |
| Measurement | Ad hoc | Consistent collection | Insights | Quantitative and qualitative |
Most organisations do not need to reach "Optimizing" in every row. The useful question is which single row is holding developers back today.
Platform design also inherits your system architecture. Golden paths are easier to standardise when services follow consistent patterns; see our guide to scalable software architecture.
Build, adopt open source or buy?
Most teams assemble an IDP from three kinds of building blocks: open source frameworks, commercial products, and in-house glue code. The right mix depends on how much platform engineering capacity you have and how unusual your stack is.
| Option | What it means | Fits when | Watch out for |
|---|---|---|---|
| Open source framework | Use a project such as Backstage as the portal layer and connect existing CI/CD and infrastructure tools | You have engineers to configure, host and maintain it | Backstage is a framework, not a finished product; plugins and upgrades need ongoing work |
| Commercial portal or platform | Buy a hosted portal or orchestration product (Gartner tracks the internal developer portals market) | You want faster time to a usable portal and fewer people maintaining it | Licence costs, fit with your tooling, and vendor lock-in |
| Build in-house | Write your own templates, CLI and automation on top of cloud and CI tools | Needs are narrow, or your stack is unusual | Becoming a second product to maintain without product management |
About Backstage specifically: it was created by Spotify and donated to the CNCF, and the CNCF project page lists it as an Incubating project, accepted on 8 September 2020 and moved to Incubating on 15 March 2022. For a broader decision method, see our build vs buy software guide.
How to measure whether your internal developer platform is working
Measure an IDP on three levels: whether developers use and like it, whether it removes waiting, and whether software delivery improves. The CNCF white paper names specific metrics for each.
| Level | Metrics named by CNCF | What to watch |
|---|---|---|
| User satisfaction and productivity | Active users and retention, Net Promoter Score, developer productivity measures such as the SPACE framework | Are teams choosing the platform without being forced? |
| Organisational efficiency | Latency from request to fulfilment of a capability; latency to build and deploy a brand-new service to production; time for a new user's first code changes | Is waiting going down? |
| Product and feature delivery (DORA) | Deployment frequency, lead time for changes, time to restore service, change failure rate | Is delivery faster without becoming less stable? |
Given DORA's finding that platform users saw lower change stability, track change failure rate and rework alongside speed. A platform that ships changes faster but breaks production more often has moved the problem, not solved it. Our guide to engineering KPIs covers how to set up these measures without turning them into targets that teams game.
Common internal developer platform challenges and how to avoid them
Most IDP problems come from treating the platform as an infrastructure project rather than a product. These are the challenges named in the CNCF and DORA research, with practical ways to avoid them.
| Challenge | Why it happens | How to avoid it |
|---|---|---|
| Low adoption | Platform built without users; adoption stuck at "extrinsic push" | Co-develop with a partner team; publish a roadmap; measure active users |
| Slower delivery | More handoffs between systems on every change (DORA) | Remove steps that add no value; keep pipelines fast; track lead time |
| Lower change stability | Platform makes it easy to push changes but does not enforce quality (DORA hypothesis) | Put tests, security checks and progressive rollout in the golden path; watch change failure rate |
| Mandated use that does not fit | Exclusive-use rules for tasks the platform handles poorly (DORA: 6% lower throughput) | Make the golden path the easiest option, not the only one |
| No leadership support | Leaders see infrastructure as cost "disconnected from their primary value streams" (CNCF) | Report impact in delivery and business terms, not tool counts |
| Security as an afterthought | Each team configures access and secrets differently | Make the platform "secure by default" (CNCF); see our SaaS security best practices |
| Over-building | Trying to cover every capability before anyone uses one | Start with a thinnest viable platform and expand on evidence |
Do you need an internal developer platform?
You need an internal developer platform when the same infrastructure and delivery work is being repeated across teams and developers wait on others to get it done. You probably do not need a formal one when a single small team owns its whole stack and rarely waits on anyone.
Typical signals are developers waiting on tickets for environments, access or pipelines; several teams building their own pipelines and templates in different ways; slow onboarding before a new engineer's first shipped change; security controls that vary by team; and services with no obvious owner.
A small team can still borrow the ideas: one shared template, documented setup steps and a basic service catalog give much of the benefit without a dedicated platform team.
What about Gartner? Gartner's "What is platform engineering?" article forecast that by 2026, 80% of large software engineering organisations would establish platform engineering teams, up from 45% in 2022. That is an analyst forecast, not a measured result. For a measured view, the DORA findings above are more useful.
How GainHQ can help
GainHQ is a custom software development company with more than 15 years of experience building software, more than 13 products delivered and a team of more than 30 people. We build and run our own products, including Payrun for HR and payroll and Gain.io for CRM and helpdesk, so we deal with delivery pipelines, environments and developer workflows every day.
If you are deciding how to structure your delivery tooling, standardise how new services are built, or plan a platform alongside a product build, our technology consulting and custom software development services can help you scope the smallest platform that removes your team's biggest bottleneck.
Frequently asked questions
What is an internal developer platform in simple terms?
It is a shared set of self-service tools, templates and automated workflows that lets developers build, deploy and run software without waiting on other teams. A platform team builds and maintains it as an internal product, with developers as its users.
What is the difference between an internal developer portal and an internal developer platform?
A portal is the interface developers use to find services, read docs and trigger actions. The platform is everything behind it: pipelines, environments, infrastructure, security and monitoring. A portal can sit on top of a platform, and a platform can also be used through CLIs and APIs.
What does IDP stand for in software development?
In this context, IDP usually stands for internal developer platform. People also use it for internal developer portal, which is the user interface of a platform. When reading vendor material, check which meaning is intended.
What are examples of internal developer platforms?
Backstage, created by Spotify and now a CNCF Incubating project, is the best-known open source framework for building developer portals. Many organisations combine it with their existing CI/CD, infrastructure-as-code and cloud tools. Commercial portal and platform products are also available.
Does an internal developer platform replace DevOps?
No. DevOps is a culture and set of practices; an IDP is a product that packages repeated DevOps work into self-service capabilities. DORA describes platform engineering as a way to scale practices like "you build it, you run it" across an organisation.
Do internal developer platforms actually improve productivity?
DORA's 2024 report found platform users had 8% higher individual productivity, 10% higher team performance and 6% higher organisational performance. It also found about 8% lower throughput and 14% lower change stability, so measure both speed and stability.
Can a small engineering team use an internal developer platform?
Yes, but it rarely needs a dedicated platform team. A shared service template, documented setup steps and a simple catalog deliver much of the value. A formal platform makes more sense when several teams repeat the same infrastructure work and regularly wait on each other.
How do you start building an internal developer platform?
Find the developer task that wastes the most time, build one golden path for it with a partner team, and measure adoption and waiting time. Expand only when that first capability is used. The CNCF Platform Engineering Maturity Model helps you judge the next step.