Overview of Internal Developer Portals

Developer productivity + engineering excellence

Internal developer portals enable developer self-sufficiency through the use of self-service actions with baked-in guardrails. At the same time, they reduce cognitive load on developers by providing an abstraction of your software and infrastructure – so that developers can easily make sense of anything in the stack and the resulting interdependencies.

But internal developer portals are also a relatively new product category in the DevOps space, with a deep potential impact on developer culture and the DevOps toolkit. Before diving into the specifics, we need to start with a high-level overview of what internal developer portals are – and the problems they solve for engineering and DevOps teams. 

In this section, we’ll distinguish between two commonly-confused categories, internal developer platforms and portals – and lay out the four pillars of an internal developer portal, along with some of the key considerations involved in implementing an internal developer portal. 

Every dev team is unique, but every portal project should begin with a basic understanding of how internal developer portals work. This includes thinking about how a portal’s technical capabilities can support the “product” experience that you’re tailoring to your dev team’s structure, culture, and practices.  

Internal developer platform or portal – what’s the difference?

An internal developer platform (IDP) is a central hub made of up the tools required to build, deploy, and manage everything DevOps – while driving a higher-order developer experience. For example, an IDP offers unified access to internal APIs, microservices, SDKs, and other resources needed for development. It also provides integrated tooling like CLI tools, build automation, CI/CD pipelines, and infrastructure provisioning.

This means that the developer does not need to work directly within a third-party tool (e.g. incident management, Appsec, observability, cloud resource, CI/CD, container management). Instead the developer accesses these tools through the platform. So instead of using Jenkins for self-service actions, the developer will use a portal to trigger an action in Jenkins – which, in this case, will be part of the platform.

The main purpose of an internal developer platform is to reduce developers' cognitive load by centralizing resources and making them more accessible. But often, the sheer scope of an IDP can prevent wider adoption. For example, while Kubernetes and cloud resource provisioning would typically fall within an IDP, most engineering orgs wouldn’t want developers to access these directly – for reasons of security, quality, and cognitive overload. 

Additionally, developers often don’t have the knowledge to interact with these resources directly, even in their abstracted platform representation. They need guardrails and guidance to set them up for success. 

So the question becomes: how can IDPs be further abstracted and “productized” to promote developer self-service, while reinforcing golden paths and providing relevant guardrails? 

Internal developer portals are the answer. They act as a user-friendly interface to the platform – abstracting the complexity of the software development environment by providing a single user interface that’s built for the questions and needs of different dev teams.

A portal’s software catalog provides developers with a strong foundation for understanding the software development lifecycle. This familiarizes developers with the tech stack, helps them understand who the owners of different services are, and lets them access documentation for each service directly from the portal – and keep track of deployments and changes made to a given service.

This information can also be invaluable to speed up the onboarding process for new developers, as well as make diagnosing and debugging incidents easier since the dependency between microservices and products within the company is clearer  

Blueprints: the building blocks of your portal

Every organization has a unique engineering tech stack, applications and resources. And an internal developer portal has to be adapted and configured to fit with both the underlying IDP – and the use cases for both portal and platform. (For example: what are the issues the organization would like to solve first: access to cloud resources, scaffolding microservices, dealing with incidents, or AppSec?) 

It can’t be the other way around. In other words, the portal can’t dictate the organization’s use cases and priorities. 

‍Blueprints are a critical piece in connecting the design of your internal developer portal to your organization’s goals, team structures, and user needs. 

Blueprints are the foundational building blocks for defining your internal developer portal. A blueprint is a metadata schema definition – each blueprint defines the assets that the portal can manage and track: basic SDLC, microservices, environments, packages, clusters, databases, as well as third party data from incident management, feature flagging, and other apps.

Blueprints are connected by relations, which define logical connections and dependencies between them (one to one, one to many, etc). Once blueprints are defined, the portal can effectively visualize and manage the software development lifecycle, and auto-populate the software catalog.

Blueprints are also where you define self-service actions and scorecards, which are pillars of the internal developer portal.

Blueprint examples

• K8s clusters
• Developer environments 
• Package dependencies

Relations examples

• The packages that a microservice uses; 
• The run history of a CI job; 
• The Kubernetes clusters that exist in a cloud account

The four core pillars of an internal developer portal

1. Developer self-service actions

Self-service actions are perhaps the most heavily-used (and loved) feature among developer users of internal developer platforms. There’s a reason for that: instead of having multiple open tabs for CI/CD, resources, Git etc, they can just use the internal developer portal with forms that simply and quickly get them what they need, even if it’s temporary (an ephemeral environment with TTL) or requires manual approval. From the platform engineer's point of view, any self-service form is completely customizable to what abstractions developers need and what they don't. Think about it this way: when you order a ticket from an airline you don't want to choose the pilot and other flight staff. The same applies for developer self-service actions: the form should only include what developers care about (thank you, Kostis Kapelonis, for this idea).

In addition to streamlining workflows, actions often provide developers with new capabilities. For example, most organizations’ DevOps would not allow a developer to provision a cloud resource on her own – requiring her instead to open a ticket to DevOps. But in a portal with self-service actions and proper guardrails, this becomes a possible, safe, and legitimate use case. 

Forms are curated by the platform engineers to provide a product-like experience for developers.

Self-service action examples

• Deploy service version
• Modify feature flag
• Spin up a developer environment for 5 days
• Modify cloud resource
• More here

2. Software catalog

The software catalog is a centralized metadata repository for software and its underlying resources, letting developers easily see and understand all entities – microservices, cloud resources, CI/CD data, Kubernetes clusters etc, developer environments, pipelines, deployments, and anything cloud tools, libraries, services, and components – in context. The catalog provides useful abstractions to developers, acting as a single pane of glass for everything software. The structure of the catalog is determined by the blueprints and relations defined in the data model (see Chapter 3 for more details). 

The catalog is always kept up to date and reflects any changes, allowing developers to know what is going on and even serving as a source of truth for matters CI/CD and becoming an asset for pipelines that can query the catalog with questions such as TTL of an environment, service ownership, feature flags and more.

3. Scorecards

Scorecards are benchmarks for each element in the software catalog. This is where metrics for quality, production readiness, and developer productivity are defined and measured. Typically scorecards are created to set engineering standards and reflect to teams where they should be going. Scorecards can also be used to trigger alerts or to be checked by CI/CD pipelines (e.g. when a scorecard is degraded, something won’t be deployed).

Scorecards can also support initiatives – groupings of related scorecards, designed to drive strategic priorities (see Chapter 5 for more details) – and campaigns to improve production readiness or quality testing practices. Automations with scorecards might include tracking open Jira issues, opening Jira tasks, or blocking deployment of low production readiness services. Scorecards and initiatives are also perfect for DORA metrics.

Scorecard examples

• Production readiness
• Service health
• DORA metrics
• Service operational readiness

4. Automation

If there’s one thing you should be thinking about more in the context of internal developer portals, it’s automations. Since portals are new, most people focus on the basics: catalog and self-service. But since the software catalog is a single source of truth for many tools, resources and software, it actually can support automations and alerts.

Think of building a catalog and then alerting on:

• Changes to scorecards, such as a degradation below a certain threshold
• Changes to software catalog entities

Automations can also be used to initiate actions, such as creating issues or triggering runbooks when a certain incident occurs. An automation might automatically terminate an ephemeral environment after its TTL (time to live) expires, or trigger an alert when scorecard assessments determine a service degradation.

Automation examples

• Incident escalation
• Security remediation
• Resource cleanup

Six portal considerations that (really) matter

Un-opinionated (vs. opinionated)

An internal developer portal can be either “opinionated” or “un-opinionated” in its design philosophy. Opinionated portals enforce a specific, predefined data model and provide a more guided experience, offering simplicity and consistency, but they are also more rigid and limiting by nature. Un-opinionated portals allow platform engineers to customize the data model to reflect the way the tech stack and use cases are in the specific engineering organization, offering more flexibility. They also let you build that data model as you grow, beginning with a minimum viable product (MVP) internal developer portal and growing it over time. 

Because every engineering organization has a unique tech stack, pain points, and degrees of visibility, opinionated portals – even if they’re sound – can end up hemming the organization in. On the other hand, an un-opinionated portal, which is more extensible and open, will allow for growth and change over time, as well as the opportunity to add more data to the catalog as the portal grows. (Read more about data models for internal developer portals here.) 

Extensible and open

An internal developer portal becomes more valuable the more data it has flowing into it – since it has a more complete software catalog, and supports a broader range of self-service actions and automations. 

Extensible and open portals are not limited by specific data sources; they allow for extensions such as bringing in vulnerability data, incident data, and other sources (third-party or in-house). It may be helpful to think of the core software catalog and portal as an inner circle, and the many potential extensions (such as auxiliary sources of data) as the outer circle. Linking additional layers means that you can add more context and information to services within the software catalog – and drive more self-service actions.

Extensibility and openness also make the portal a complete, up-to-date, single pane of glass into your environment and SDLC metadata – making it ideal for observability and pipeline automation (e.g., CI/CD). 

Loosely coupled

Why is a loosely coupled design for your portal widely considered a best practice in the industry?

• Most of the time, companies already have core tools and ways of working. They’re looking for a portal that will organically connect and integrate with their existing tooling and workflows. 
• Those that don’t are looking to build best-practice platforms (e.g., they’re using K8s native platforms for GitOps) – and don’t need or want their portal to force them to make certain platform choices.

Loosely coupled portals also provide flexibility in case changes are made to the underlying platform – making them easier to maintain and scale.

API-first 

An API-first portal will have a generic interface to model the software catalog, ingest data, invoke actions, query scorecards and more – providing an optimized experience for both humans and machines. 

This single API for the entire catalog is used for:

1. Building the catalog

Update the software catalog using a script, bringing any data into the portal, or importing an existing asset inventory from a .csv file or another portal. It can also be used to define the  data model, permissions, views, settings, actions, and any portal configuration, as well as reporting the status of a running CI job (CI/CD catalog). 

2. Automations

Integrate the portal with your custom CI/CD and support programmatic automations and alerts (like Slack messages on software catalog changes).

Portal-as-code

Portal-as-code describes an approach to configuring and customizing the portal itself through code. This can be done with tools like Terraform. It also promotes better visibility, as all changes are documented and traceable in the code repository. Portal-as-code is useful when you want to control the portal’s stability and avoid unplanned change. If you’re taking a Portal-as-code approach you have a process in which the portal is defined, in one place, with all changes tracked and the ability to revert if needed. 

Customizable

A product-like experience ensures that developers will be able to answer the questions that matter to them –  while interacting with the right abstractions, accessing the right self-service actions (with appropriate guardrails), and engaging with scorecards and reporting relevant to their roles. 

Your portal should support platform engineering in building this product experience for your developer users. This requires customizability of views, visualizations, and UI – along with fine-grained role-based access controls – for different “personas” (teams and roles). It also requires the ability to deliver the right resources to specific users in context: for example, documentation to a developer drilling down into an individual service in the catalog.