What is an Internal Developer Portal?
An Internal Developer Portal is a centralized organizational hub that provides developers with simplified self-service access to all the tools and information they need to build, deploy, and manage applications. These include container registries, vulnerability scanners, CI tools, IaC tools, control planes, information on how microservices are connected, and more. To further guide developers, the Internal Developer Portal prescribes "Golden Paths" in —best practice workflows for each tool and resource, which developers can enact via self-service actions or through scorecards and quality initiatives.
The Internal Developer Portal acts as a single, centralized, easy-to-use and straightforward source of truth for software development operations. Through self-service actions, a software catalog that is searchable and in graph form, developers can easily find, access and use the tools they need. Otherwise, they would have to navigate distributed resources and systems or request assistance from DevOps. As a result, developers can carry out all actions and reduce the cognitive load that accompanies the complexities of operations and development, which streamlines the development process.
The Software Catalog
One of the key components of the Internal Developer Portal is the software catalog. The catalog is a centralized metadata repository for all software-related information. It provides developers with a comprehensive and simplified view of all operational components: microservices, cloud resources, CI/CD data, Kubernetes clusters, and more. The catalog's structure is shaped by blueprints and relationships and it is continuously updated. This makes it a reliable source of truth for CI/CD processes and for developers who can query the catalog for specific information.
Internal Developer Portal vs. Internal Developer Platform
The Internal Developer Portal is often confused with the Internal Developer Platform. The two terms are interconnected, but they are not synonymous. While the Internal Developer Platform is made up of the tools that allow self-service, the Internal Developer Portal is the interface that enables developers to access all platform resources through golden path self-service actions. Both resources are built, configured and maintained by platform teams.
The 5 Internal Developer Portal Principles
The specific features and functionality of an Internal Developer Portal will vary depending on the needs of the organization. However, there are five principles that all internal developer portals should abide by:
- Product-like Experience: The Internal Developer Portal should allow platform engineers to act like product managers. This includes adding visualizations per team and dev, abstracting information, selecting the self-service actions that matter most to developers and controlling the look and feel of forms, as well as the fields contained in them. In addition, the tools should be decoupled from the infrastructure, enabling changes in the infra without impacting the developer experience.
- Compliant and Secure by Design: The Internal Developer Portal sets the security and compliance requirement. With the portal, a developer can't scaffold a new service or perform any other action without meeting these requirements. Otherwise, this will be reflected in the scorecards. As such, the portal drives better engineering standards.
- Central: The Internal Developer Portal should be a central place all developers have access to (according to compliance requirements, RBAC permissions and security guardrails). Therefore, it is always up-to-date. In addition, the portal is also the central place for storing all tools and infrastructure data, supporting use cases such as package management.
- Self-service Support: The Internal Developer Portal is not (only) a knowledge base or documentation hub. Through the portal, developers are able to perform all operational actions independently: day 2 operations, provisioning, microservice scaffolding, requesting temporary permissions, spinning up ephemeral environments, and more. The portal supports this through the UI.
- API-first: The Internal Developer Portal is not just for developers, it’s also for machines. Interfaces should support automated triggering of DevOps workflows and pipelines.
Why Does an Internal Developer Portal Matter?
An Internal Developer Portal is a strategic organizational asset that accelerates time-to-market and improves the developer experience. Here's why it matters:
- Cognitive Load Reduction - By creating golden paths and eliminating the need for developers to think about how to use DevOps tools, developers can instead focus on coding and Git. This allows them to concentrate rather than task sprawl.
- Streamlined Workflow - Developers often need to juggle multiple tasks, from coding and debugging to integrating APIs and scaffolding new services. An Internal Developer Portal centralizes all necessary resources and enables taking straightforward actions on them, reducing the time developers spend searching for information and increasing their productivity and velocity.
- Standardization and Best Practices - A portal can serve as the standard-setting center for coding, terminology, best practices, architectural guidelines and tools. This ensures that everyone is on the same page, leading to more consistent and higher-quality code.
- Faster Onboarding - New hires can get up to speed more quickly when they have a centralized resource to guide them. This reduces the learning curve and allows them to contribute to projects sooner. The portal can also accelerate the adoption of new tools.
- Productivity and Cost Savings - An internal developer portal reduces the time developers spend on mundane tasks like searching for documentation or figuring out how to use an API, the time senior developers are spending on answering their questions or training them, and the time DevOps are taking to run operations for them. Saving this time reduces technical debt and MTTR, cuts cloud costs, and more — effectively cutting costs.
- Innovation - When developers have easy access to resources and a platform for collaboration, they are more likely to experiment and innovate, potentially leading to new products or improvements in existing ones.
Internal Developer Portal Use Cases
An Internal Developer Portal can serve multiple purposes, each addressing specific needs within an organization. The developer portal should be designed according to each organization’s specific needs. That being said, here are some common use cases based on integrations with third-party tools:
Developer routines that can be performed in the internal developer portal:
- Incident management
- AppSec management
- Setting up ephemeral environments
- Managing feature flags
- FinOps
Developers:
- Environment deployments (canary, blue/green)
- Feature flags
- Spinning up development environments
- Cloud resource modification
- Monitoring runtime performance
Product Managers:
- New tool adoption
- Feature usage
Executives:
- Tracking usage
- Tracking system health
- Tracking business impact
CIOs:
- Benchmarking the use of services
- Benchmarking components reuse
- Monitoring productivity metrics
- Defining and monitoring quality and other engineering initiatives
Common Pitfalls When Adopting an Internal Developer Portal
Adopting an Internal Developer Portal can offer numerous benefits, but there are also pitfalls that organizations should be aware of to ensure successful implementation and adoption. Here are some common challenges:
- Lack of User-Centric Design - A portal that is not intuitive or user-friendly can deter developers from using it. Involve developers in the design process and conduct usability tests to ensure the portal meets their needs.
- Incomplete or Outdated Workflows - Inaccurate or incomplete workflows can lead to confusion and errors. Establish a process for regularly updating workflows, like scorecards, and make it easy for developers to track them.
- Lack of Governance - Without proper governance, the portal can become cluttered with outdated or irrelevant information. Assign a dedicated team or individual to manage the portal's content and structure. The internal developer portal software catalog is the cornerstone of this work.
- No Self-Service - The Internal Developer Portal should be designed as a comprehensive tool that empowers developers to perform a wide range of operational tasks autonomously. Treating the portal as a knowledge base and failing to provide these capabilities can lead to bottlenecks in the development process and reduce overall productivity.
- Insufficient Onboarding and Training - New users may find the portal overwhelming if there's no guidance on how to use it. Create onboarding tutorials or guides to help new users navigate the portal.
- Security Concerns - Sensitive information could be exposed if the portal is not secure. Implement strong authentication and authorization mechanisms and regularly audit for security vulnerabilities.
- Resistance to Change - Developers accustomed to their own ways may resist using the portal. Communicate the benefits clearly and consider a phased rollout to help users adapt.
- Lack of Analytics and Feedback - Without analytics, it's hard to measure the portal's effectiveness or identify areas for improvement. Integrate analytics tools to track usage patterns and gather feedback from users for continuous improvement.
Learn more about the Internal Developer Portal from the following resources:
