Internal developer portals: what you need to know

Internal developer portals are one of the leading tooling categories in the emerging space of platform engineering. The explosion of platform engineering as a trend and a community within the broader cloud native industry has fueled the growth of the portal landscape, with commercial offerings popping up left right and center to complement existing open source solutions.

According to Gartner, “By 2026, 75% of organizations with platform engineering teams will provide internal developer portals to improve the developer experience and accelerate product innovation, up from 45% in 2023”.

Source: Market Guide for Internal Developer Portals, Gartner, Manjunath Bhat, Oleksandr Matvitskyy, Mark O'Neill (behind paywall)

As with most new trends, however, it can be tricky to understand best practices and how to find the right tool for your specific needs. This guide will provide you with all the necessary information needed to evaluate internal developer portals as a category and identify which specific open source or commercial portal is best for your platform engineering setup.

What is an internal developer portal (and how does it differ from an Internal Developer Platform)?

TL;DR:

Internal developer portals serve as the interface through which developers can discover and access internal developer platform capabilities.

‍Source: A Software Engineering Leader’s Guide to Improving Developer Experience, Gartner, Manjunath Bhat (behind paywall)

You should think of an internal developer portal as one of the main interfaces that application developers use to interact with the Internal Developer Platform (IDP).

The image below shows how the portal is one of the many components that make up an IDP. It sits in the Developer Control plane, alongside other interfaces and application developer tooling (e.g. IDE and VCS).

Now, both the internal developer portal and Internal Developer Platform are abbreviated to IDP, which is where confusion often sets in. However, the difference really is quite simple. The portal is a subset of your enterprise Internal Developer Platform. It’s one of the interfaces INTO your platform.

Many companies mistake one for the other. They (wrongly) assume that building or buying a portal equals implementing a full-blown platform that covers all your enterprise needs. While portals are a great tool and play a key role in your platform engineering initiative, a portal by itself without for example a Platform Orchestrator, can provide you with relatively limited functionality.

Another major difference is that you can’t really buy an IDP (as in an Internal Developer Platform), you can only build one. For portals on the other hand, there are off-the-shelf offerings. If you want to dive deeper into the difference between portals, platforms, and PaaS, we have a dedicated article on the topic.

Key features of an internal developer portal

Service catalog: This is probably the most fundamental feature of a portal. In fact, before internal developer portals recently emerged as a platform engineering category, older solutions in the space such as Backstage were commonly called service catalogs.

The idea of a service catalog is quite simple. You get a list of all the apps and services in your engineering organization, with clear metadata such as ownership, as well as relationships and dependencies with or on other services.

One of the original promises of the service catalog is to enable full reusability of services across multiple product teams, avoiding redundant development. While this sounded great in theory, it proved to be far trickier to implement in practice. This is because tweaking existing code to fit new use cases can sometimes take as long as, if not longer than, starting from scratch when using a simple template. Most organizations today use portals to enable service scaffolding but don’t aim for full reusability.

Dashboards: Portals are a management favorite because they let teams clearly visualize not only dependencies and service status (e.g. what’s running where), but also important metrics. Common examples are dashboards for DORA and other performance metrics, as well as general org intelligence and cost control measurements.

Portals can also show platform performance and adoption metrics. However, it’s important to be mindful of potential perverse incentives here. People and managers responsible for shipping and rolling out the platform might want to make the case for their platform, even when the organization is not responding well to it.

Integrations: A portal should easily integrate with all other key elements of your platform, i.e. connect to tooling across all five planes. This is a key functionality to be able to provide a full picture of the organization, reading in inputs from all parts of your IDP.

Score cards: This is a relatively new entry on the list of internal developer portal features and something that older solutions don’t really offer. Score cards are provided by the latest generation of portals to display the general health of apps and services, as well as compliance with security policies, permissions, and governance.

Developer self-service: Portals let developers self-serve templates and execute workflows in an automated and standardized way. For example, engineers can consume service blueprints that follow the latest compliance standards set by the security team. The self-service is limited to what tooling the portal is connected to, e.g. if wired to a Platform Orchestrator, devs will be able to use the portal to self-serve any piece of infrastructure they want to consume.

RBAC: Similarly, when it comes to Role-Based Access Control (RBAC), the latest generation of portals connect to tools like SSO and a Platform Orchestrator to let security and platform teams define clear roles and permissions that work across all teams and workflows. This is a key functionality and integration for any portal that should be deployed in an enterprise setting.

‍Auto documentation: Portals are not only a key interface to your IDP, they’re also a very important source of documentation. They provide access to logs, diffs, and the enterprise-grade offerings document everything as code, which is again crucial for auditability and security.

Primary use cases of an internal developer portal?

Faster developer onboarding: Using a portal, new hires can be quickly onboarded to your platform setup and underlying toolchain. They have a single pane of glass that abstracts the complexity of your infrastructure and lets them get started quickly.

This doesn’t mean that the portal abstracts everything away from the developer or entirely restricts access to configurations. It’s crucial in platform engineering to ship your IDP (i.e. your portal too) following a platform as a product approach. This means the platform team needs to iterate on both the platform and portal based on developers’ feedback. It’s the only way to build golden paths that abstract complexity without removing all the necessary context from developers.

Unified developer experience (DevEx): Developer portals are one of the best ways for engineering organizations to provide a very consistent DevEx. This is possible for every engineer in the company, regardless of which team they sit in or what their level of expertise with certain tools is. The platform team at Netflix gave a very insightful talk on the topic at PlatformCon23.

Inner-sourcing: The service catalog feature makes it easy to discover existing services that are being developed or used by other teams. Although this prevents companies from doubling efforts, as discussed above, it’s more helpful for broader alignment than for full reusability.

Scaffolding from templates: Developers can use the service templates available in the portal to quickly get started building, knowing they’re following the latest security standards and configuration blueprints of their organization.

Track metrics: Despite their name, internal developer portals are often used by management too. Dashboards with automatically tracked metrics on developer productivity and team performance, as well as ownership metadata in service catalogs all provide valuable information to help make more informed decisions.

Internal developer portal offerings

Below is an overview of the main portal solutions in the market today. This will soon be complemented by a more granular comparison table.

Backstage: The O.G. portal, originally open sourced by Spotify who built it internally as a service catalog for their engineering org. This is also the most popular portal offering by far (whether in terms of search traffic, forks, or mentions). However, it’s not easy to configure to fit the needs of a given organization and it’s hard to maintain. Because of that, companies that offer it “as a service” (e.g. Roadie) have gained some traction. Backstage is also integrated into broader offerings like VMWare Tanzu.

Because of the complexity of installing and rolling out Backstage, few closed source, commercial alternatives have gained market share in the last two years:

Cortex: This developer portal vendor offers a catalog, scorecards, a scaffolder, and many integrations. Read how Cortex works hand-in-hand with the Humanitec Platform Orchestrator.

Humanitec Portal: Humanitec has launched its own portal to complement its core Platform Orchestrator offering and open source workload specification (Score). This now makes Humanitec an ideal one-stop-shop option for platform engineering in the enterprise.

Getport.io: Getport.io is a commercial portal vendor that works hand in hand with Humanitec. Its main features include a catalog, scorecards, automation, and dashboards.

Configure 8: Another commercial portal vendor offering a catalog, scorecards, and automation along with upcoming cost management features.

OpsLevel: The main offering is a catalog with AI support to create metadata, Docs-as-code.

Rely: Rely offers a catalog, scorecards, dashboards, and SLO tracking.

Compass by Atlassian: Officially launched in October 2023, Compass natively integrates with JIRA and will be offered free of charge to all Jira users, making it extremely easy to go from grooming to production, in one flow.

Note that all internal developer portals can be used as interfaces for an Internal Developer Platform built around Humanitec Platform Orchestrator and Score.

You can choose any portal you want to use or use Humanitec’s own Portal offering.

Drive more value with a portal and IDP 

Portals can provide great value for engineering organizations by enabling service discoverability and templating, improving DevEx and onboarding, and providing transparency around key performance metrics. 

But it’s important to remember that they’re really designed as interfaces into your platform, not as the platform itself. Internal developer portals do not solve the underlying configuration and infrastructure orchestration challenges that can only be tackled by an enterprise-grade IDP. If you’re interested in building a truly enterprise-ready IDP, check out our reference architectures built with the Humanitec Platform Orchestrator.