GainHQ
Go back

Internal Developer Platform Best Practices For Modern Software Teams

Internal Developer Platform Best Practices For Modern Software Teams

by GainHQ Editorial Team | May 31, 2026 | Software Development Insights | Editorial policy


Table of Contents
  1. What is an internal developer platform?
  2. Internal developer platform vs internal developer portal
  3. What an internal developer platform includes
  4. What does an internal developer platform look like in practice?
  5. Benefits of an internal developer platform, and the trade-offs
  6. Internal developer platform vs DevOps vs platform engineering
  7. How to build an internal developer platform
  8. Build, adopt open source or buy?
  9. How to measure whether your internal developer platform is working
  10. Common internal developer platform challenges and how to avoid them
  11. Do you need an internal developer platform?
  12. 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 portalInternal developer platform
What it isA front door: web UI with catalog, docs and self-service actionsThe 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 contentsSoftware catalog, service ownership, scorecards, templates, TechDocsCI/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 themYes, through CLIs, APIs and templates without a portal
Open source exampleBackstage, "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 seesExample of the self-service action
Web portals and APIs for provisioningA catalog and "create" buttons, or an API/CLIRequest a new service from a template
Golden path templates and docsStarter repositories with build, test, deploy and monitoring wired inScaffold a service that passes security checks from the first commit
Build and test automationShared CI pipelinesUnit and integration tests run without the team owning the runners
Delivery and verification automationStandard deployment pipelinesPromote a build from staging to production
Development environmentsOn-demand environmentsSpin up a preview environment for a pull request
Application observabilityLogs, metrics and traces by defaultDashboards created when the service is created
Infrastructure, data and messaging servicesManaged compute, databases, queuesProvision a database with backups configured
Identity, secrets and security servicesBuilt-in access control and secret storageRotate a credential without a ticket
Artifact storageShared registriesPublish 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.

StepWithout a platform (illustrative)With a golden path (illustrative)
1. Create the serviceCopy an old repo, remove what is not neededChoose "Backend service" template in the portal
2. Set up CI/CDWrite a pipeline, ask DevOps to review itPipeline included in the template
3. Get infrastructureRaise a ticket for a database and environmentSelect "needs PostgreSQL"; the platform provisions it
4. Secrets and accessAsk security for credentialsSecrets injected from the shared secret store
5. ObservabilityAdd logging and dashboards later, if rememberedLogs, metrics and alerts created by default
6. Ownership and docsUpdate a wiki pageService 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 productivity8% higher
Team performance10% higher
Organisational performance6% higher
Software delivery throughputAbout 8% lower
Change stability14% 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 team6% higher (negligible for individuals)
Throughput when developers must use the platform exclusively for the whole lifecycle6% 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.

  1. 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.
  2. 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.
  3. 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.
  4. Decide what to build, adopt or buy (see the next section). Most platforms are assembled from existing tools rather than written from scratch.
  5. 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.
  6. 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.
  7. 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:

AspectProvisionalOperationalScalableOptimizing
InvestmentVoluntary or temporaryDedicated teamAs productEnabled ecosystem
AdoptionErraticExtrinsic pushIntrinsic pullParticipatory
InterfacesCustom processesStandard toolingSelf-service solutionsIntegrated services
OperationsBy requestCentrally trackedCentrally enabledManaged services
MeasurementAd hocConsistent collectionInsightsQuantitative 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.

OptionWhat it meansFits whenWatch out for
Open source frameworkUse a project such as Backstage as the portal layer and connect existing CI/CD and infrastructure toolsYou have engineers to configure, host and maintain itBackstage is a framework, not a finished product; plugins and upgrades need ongoing work
Commercial portal or platformBuy 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 itLicence costs, fit with your tooling, and vendor lock-in
Build in-houseWrite your own templates, CLI and automation on top of cloud and CI toolsNeeds are narrow, or your stack is unusualBecoming 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.

LevelMetrics named by CNCFWhat to watch
User satisfaction and productivityActive users and retention, Net Promoter Score, developer productivity measures such as the SPACE frameworkAre teams choosing the platform without being forced?
Organisational efficiencyLatency 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 changesIs waiting going down?
Product and feature delivery (DORA)Deployment frequency, lead time for changes, time to restore service, change failure rateIs 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.

ChallengeWhy it happensHow to avoid it
Low adoptionPlatform built without users; adoption stuck at "extrinsic push"Co-develop with a partner team; publish a roadmap; measure active users
Slower deliveryMore handoffs between systems on every change (DORA)Remove steps that add no value; keep pipelines fast; track lead time
Lower change stabilityPlatform 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 fitExclusive-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 supportLeaders see infrastructure as cost "disconnected from their primary value streams" (CNCF)Report impact in delivery and business terms, not tool counts
Security as an afterthoughtEach team configures access and secrets differentlyMake the platform "secure by default" (CNCF); see our SaaS security best practices
Over-buildingTrying to cover every capability before anyone uses oneStart 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.

Related Blogs