Internal developer portals: top 10 selection criteria

A guide to the 10 things internal developer portals must have

A successful portal requires the same ingredients

Internal developer portals come in all shapes and sizes. 

However, the one thing they all have in common is that they provide one place that offers a unified developer experience - with the information managers and developers actually need, yet abstracted and made easy to consume. To deliver on this promise, platform engineers should use a product-driven approach to ensure the portal delivers a compelling developer experience. To do that, there are certain elements - approaches, strategies and features - that a portal ought to have. 

Here’s our take on the 10 things all internal developer portals should have:

• A portal as product approach 
• Ability to deliver an end-to-end developer experience
• A bring-your-own-data-model approach to support any engineering DNA and make the portal future proof
• Personalized and customized experiences
• API-first
• Automations
• Portal as code
• No-code RBAC
• Quick time to value
• Secure by design

1. A portal as product approach 

Portals need to provide compelling experiences. It’s not enough to bring everything the developer needs into one place. The portal needs to be considered as a ‘product’ for developers; it needs to be intuitive, taking away complexity and reducing cognitive load. A product approach means collecting feedback from developers (and other users) of what they need, what their pain points are and what features they would like to have access to. If your users aren’t convinced that your portal is worth using, it won’t work, and the same approach needs to be taken when considering the platform and what self-service actions it supports. 

Platforms continuously evolve and therefore the product experience offered on top of them, through the portal, will also naturally evolve. The ability to define and build a product experience and to evolve it is crucial and the portal needs to support this. 

To do this a portal needs the right building blocks:

• This begins with the ability to define metadata schema (and their relationships) that connect the design of your portal to your organization’s goals, team structures, and user needs. In Port this is called blueprints.
• Self-service Actions which enable developers to get what they need quickly and simply through a product like experience where they simply fill a form that’s made to fit the knowledge of the user and provide them with the right guardrails.
• A software catalog - a centralized metadata repository for software and its underlying resources, serving as a source of truth and letting developers see, query and understand all entities.
• Scorecards to benchmark each element in the software catalog for quality, production readiness and developer productivity.
• Automations, enabling alerts from a software catalog and scorecards such as any changes. Also can be used to initiate actions such as creating issues or triggering runbooks during an incident. 
  
• Data model flexibility to evolve as the underlying platform changes and grows.
• Be loosely coupled with the platform.
• Support an open approach that can ingest any data into the portal, allowing the developers to see all they need in one place.

Using the above, a platform engineer can build the right experiences to best serve developers and managers and quickly define use cases and developer workflows.

Read more:

• Leveraging product management strategies for your developer portal
• How platform as product and portal as product work together
• Understanding how the Internal Developer Portal and platform connect

2. Support an end-to-end developer experience

With the internal developer portal, developers can access one place to serve all their development needs, throughout the software delivery lifecycle. 

Instead of dealing with the complexity and discoverability issues of a cloud native architecture, too many developer tool interfaces and cognitive load, developers only need to work with three interfaces: their IDE, their git repository and the developer portal.

Internal developer portals should support the developer experience during the different phases of the developer workflow:

• Plan the day: Developers can manage pull requests, view Jira tickets, check on-call rotations, and prioritize tasks.
• During development: The portal provides access to API documentation, service ownership details, tools for infrastructure as code (IaC), and other resources needed for coding, testing, and managing configurations.
• Shipping features: When it’s time to ship, the portal supports building, promoting, deploying, as well as running migrations and managing canary releases.
• Production operations: Post-deployment, the portal is used to help understand service health, manage incidents, troubleshoot outages, and perform necessary actions like database permissioning or service restarts.

An end to end developer experience requires:

• Full coverage of all self-service actions - from setting up through day 2 operations
• Supporting long running actions and providing the right run logs
• The right abstractions of data so that developers understand what matters to them
• Alerts using automations
• Integrating with all developer tools needed to provide an end-to-end experience

Read more:

• Give day-2 operations autonomy to your developers
• Setting up a Git-based internal developer portal & extending the data model with Kubernetes
• Internal developer portal: how do I get started?

3. A flexible data model that supports any engineering DNA and can evolve

Each engineering organization is unique and portals should therefore be un-opinionated and flexible so you can make the portal and resulting practices fit with the way you work. 

In short, a portal should fit your stack, standards, and processes, not the other way around. It should also be able to evolve when your needs and underlying platform change.

• You should be able to define any software catalog entities needed to support the right visibility and functionality for your stack, their properties and the relationships between them.
• The portal should be open to including any metadata, so you can connect to your tooling and ingest data using out of the box integrations.
• Any data ingested into the portal should be added to the same central metadata store, meaning it is simple to query and always appears within the context of the software catalog graph, so you can quickly add feature flag, cost, appsec and any other data and see it in context. This is unlike the approach of plugins in open source developer portals, which just display the data but keep it outside the central metadata store.
• You should be able to build anything relevant in the software catalog, which can contain anything from packages, K8s clusters, services, vulnerabilities, events, APIs, ephemeral environments etc
• The data model flexibility should also extend to scorecards, so you can easily track production readiness, ownership or documentation or even ensure that your cloud resources are tagged for FinOps purposes.

Engineering is always changing, as are tools, needs and even developer responsibilities. Only data model flexibility can ensure your portal choices are future proof. As developers and ecosystems change, you can change the experience you provide.

4. Support personalized and customized experiences

The portal should support customization (logo, colors) but more importantly, it should support the creation of personalized experiences for different teams, roles, developers and personas.
This can be accomplished using: 

• RBAC that’s granular and applies both to data and self-service actions allowed.
• Folders which enables you to organize your portal by role, use case or team, making it easier for everyone to find what they need.
• Self-service forms, manual approvals, and fields according to the specific persona and show them the run logs they need.
• Personalized dashboards according to each persona’s need, RBAC and team

Read more:

• How Can Different User Personas Get The Best Out of An Internal Developer Portal?
• Announcing Dashboards
• Curate Personalized Experiences with Folders

5. API first

API first means that every portal functionality, including actions, data retrieval, pages, and dashboards, should be accessible through API calls. This architecture means that every operation can be performed either through the UI or the API, and every piece of information visible in the UI can be queried with an API operation, Using an API first approach, a portal supports interoperability and automation with your platform tooling and provides value as a single source of truth about anything in the SDLC.  

• all functionality should be exposed through APIs, not some of it.
• Being API-first allows you, for example, to integrate your CI tool to check software catalog data before pushing new features to production.
• You can also write SDKs that are using the portal data and functions  
• Self service actions could consume portal information using port APIs

6. Automations

Since a software catalog centralizes all the information you care about and is updated in real-time, you can create automations which are using this information. Automatic response mechanisms ensure that actions are always aligned with the latest insights, fostering a proactive operating environment.

• Automations can trigger actions based on software catalog data. These can be anything from timely notifications and alerts to executing operational tasks.
• Notifications can indicate when a scorecard for a service degrades, a new critical vulnerability has been identified in production, and more.
• You can also use automations to trigger a DevOps workflow- such as terminating an ephemeral environment when a TTL expires.

7. Portal-as-code

You can set up and customize the portal through code using an infrastructure as code tool such as Terraform. With this method, the portal setup and adjustments can be made as code changes and can be version controlled, reviewed, and audited. This strategy ensures all the portal configurations are documented, version-controlled and reversible, offering a more reliable and stable environment.

This can also simplify RBAC management for the portal, the Terraform logic can be the one making changes in the data model and the actions, while users only have their appropriate limited permissions. This means that the only user who can make changes to the portal always undergoes a review process, so both the platform engineers and the developers are never surprised by the changes happening in the portal.

8. No code RBAC

Use no-code RBAC to easily abstract information and provide the right information to users.

Define granular policies and permissions regarding software catalog data and self-service actions.

The RBAC model should cover: 

• Developer portal permissions 
• Policies for self service 
• SSO and ownership permissions 
• Audit log 

9. Quick time to value

As a highly visible project, set in an ever evolving ecosystem, the portal needs to be quick on its feet. You need a quick MVP, access to templates and examples, knowledge and inspiration. 

With an easy to implement portal, organizations can address the most pressing use cases and quickly deploy new offerings to portal users. This is why a platform for building no-code Internal Developer Portals is key, making it simpler to create the portal you need. In addition, you’d want to consider being able to get the most out of your numerous plugins as quickly as possible - this means considering a portal that has:

• A unified UI across all integrations and experiences
• A unified data model across plugins so that you can create cross-plugin queries, and so that all plugins feed a unified UI and dashboards
• Extensibility and customizability
• Consistent coverage, maintenance and support

All this allows for quick refinement and iteration, which delivers immediate value and sets the stage for scaling to more use cases or expanding to additional users.  

A community-driven portal is best for this, as well as the ability to understand what’s next, using an open roadmap.

10. Secure by design

Robust security is critical to protect your portal and your development environment

• Sensitive data like secrets or credentials should not be stored in the portal, and portals should not require IP whitelisting or inbound network calls into customer networks.
• Communication should be secure and uni-directional, originating from a stateless broker that operates without the need for database migrations or concerns of downtime.
• The portal should only store the metadata that customers choose to send through brokers or APIs. Customers have full control over what data is collected, ensuring nothing is ingested without explicit consent. Data should be pushed to the portal without the need for inbound networking, and permissions for the collection are finely controlled by the customer, including configurable data retention periods.

The Recipe for Portal Success

No one portal is the same. Every organization has its own requirements and stakeholders. However, there are some things platform engineers will need no matter what. This list should help guide you when considering your options for a developer portal.

For a guide that dives deeper into each of the portal’s key pillars, check out our Practical Guide to Internal Developer Portals.