Internal developer portal

What is an internal developer portal?

July 14, 2024

Sooraj Shah
Sooraj Shah
What is an internal developer portal?
Example H2

Ready to start?

What is an internal developer portal? 

An internal developer portal provides developers with an interface to find and access the capabilities they need from their internal developer platform. It enables them to self-serve, find, access, understand and manage anything in the SDLC with ease, reducing their cognitive load. In Gartner’s Top five strategic technology trends in software engineering for 2024 report, the analyst firm said portals and other platform engineering platforms provide a “paved road” to software development, saving time for developers and improving job satisfaction. 

Here is the definition in Gartner’s own words:

“Gartner defines internal developer portals as tools that enable self-service discovery, automation and access to reusable components, tools, platform services and knowledge assets in modern software development environments”.

Why do you need an internal developer portal? 

Over the last decade, DevOps has revolutionized software development by introducing practices that promote agility, rapid deployment to production, and self-sufficiency within engineering teams. This paradigm shift involved creating scalable, automated development lifecycles with microservices, Kubernetes, and cloud resources. 

At the same time, with shift-left, developers’ responsibilities expanded to include feature delivery, incident management, and cloud interactions. They were also required to adhere to organizational security, quality, and compliance standards.

The result is a paradox: making developers responsible for more things, with the expectation of more productivity and better software quality, while the environment is getting more complex and more distributed, which is actually slowing developers down.This DevOps paradox manifests in various ways:

  • Lower productivity: in some cases, lower productivity is a result of developers waiting for tickets - such as SRE reviews. In others, when developers self-serve, the complexity introduces cognitive load and results in lost time. In all cases, complexity that isn’t made easier for developers hurts productivity.
  • No central source of truth - in most cases, there is no up to date central repository of all metadata that is related to DevOps and SDLC assets. As a result, it’s difficult for DevOps and developers to easily answer questions such as which services running in production have critical appsec vulnerabilities or are not production ready.
  • Degraded quality, security and compliance: Tracking numerous distributed elements is increasingly challenging, leading to issues in maintaining AppSec, cost, production readiness and other standards.
  • Inefficient onboarding: The complexity and abundance of moving parts made it difficult to efficiently integrate new developers.
  • Incident management difficulties: With numerous potential incident causes and the required extensive knowledge base, managing incidents became highly complex.

In response to these challenges, leading companies like Spotify, Netflix, and Lyft developed in-house internal developer portals, initiating the current platform engineering revolution. According to Gartner, by 2026, 75% of organizations with platform engineering teams are expected to implement such portals. 

What’s the difference between internal developer portals and external developer portals?

An external developer portal serves external developers, partners, or customers who interact with an organization’s APIs, SDKs, and other developer resources. External developer portals are usually set up in order to assist in the creation of an external developer community. They contain documentation, support and anything else required to support those external developers creating an ecosystem for an external developer community. 

An internal developer portal serves the internal engineering organization. By providing a unified interface, an internal developer portal facilitates collaboration, ensures compliance with organizational standards, and improves overall transparency within the development lifecycle. It serves as a hub where developers can work more autonomously while adhering to best practices and security protocols. Engineering managers use the portal to track metrics and standards and improve the SLDC, driving productivity and standards compliance.

Internal developer platform vs internal developer portal

Internal developer platforms and internal developer portals, despite their similar names and shared goal of improving the developer experience, serve distinct yet complementary roles within an organization's software development infrastructure. 

The internal developer platform  is a comprehensive suite of tools and services for building, testing, and deploying applications, allowing developer self-service for configuration, deployment, provisioning, and rollback. This idea of “reusable self-service actions” is what ties together the tools and infra that make up the internal developer platform. This ability to self-serve abstracts the complexities of underlying systems, allowing developers to concentrate on coding and delivering features.

On the other hand, the internal developer portal acts as the user interface for the platform. It centralizes access to all necessary tools, resources, and documentation, providing a unified and user-friendly interface. The portal enhances the developer experience by simplifying access and usability, facilitating self-service capabilities, and improving overall productivity. Key functionality include a service catalog, workflow automation, and comprehensive documentation, all aimed at reducing cognitive load and making it easier for developers to find and use the tools provided by the platform.

While the internal developer platform focuses on infrastructure management, reusable self-service actions, and automation of integration and deployment processes, the internal developer portal focuses on improving the user experience. It does this by abstracting the complexities of infrastructure and offering direct interaction through a unified interface. This ensures that developers can work more efficiently without needing to understand the intricacies of each tool within the platform.

In summary, the internal developer platform provides access to the  backend infrastructure necessary for software development, while the internal developer portal enhances the developer experience by providing an accessible and intuitive interface for interacting with these tools. Together, they form an essential structure that optimizes productivity, standardizes processes, and simplifies the complexities of software development, enabling organizations to build, deploy, and manage applications more efficiently and effectively.

What are an internal developer portal’s components? 

An internal developer portal is a centralized hub designed to enhance developer autonomy, productivity, and visibility into engineering activities; for managers it serves to measure and improve engineering quality, standards adherence, processes and productivity. Developers use it to bring information in one place and for self-service actions.

The main pillars of a portal are:

  • A service catalog or software catalog which is a central metadata repository and system of record that reflects the entire SDLC, helping developers to understand the tech stack, service ownership and documentation, in context, thereby easing onboarding, incident management and many other use cases. The catalog is required for all of the subsequent pillars. The catalog improves the developer experience by enabling developers to find what they need, reduce manual work, and re-use assets more readily.  
  • Developer self-service, enables developers to take actions without needing to wait for DevOps or ticketops or navigating different tools. Using simple forms, developers can execute actions with built in guardrails and golden paths. These forms trigger self-service actions that are built in the platform.

‍

  • Scorecards can grade production readiness, code quality, migrations, operational performance, and more. By defining scorecards for assets in the organization's software catalog, organizations can set standards, track them and drive developers to fix non-compliance. Scorecards are an essential tool for managers seeking to understand anything from developer productivity to production readiness and AppSec compliance. 
  • Dashboards enable efficient data visualization and access. Since all the data is already consolidated in the portal’s software catalog, with the associated scorecards, you can present the relevant data to developers, DevSecOps, FinOps and management, showing them the right visualizations and allowing them to take action, using self-service actions that can be embedded into the dashboard.
  • Automations tie together the different pillars of the portal, impacting efficiency and operations. They bring process orchestration to complex workflows, ensuring smooth operations with minimal manual intervention. They enable teams to automate repetitive tasks, better utilize notifications and alerts, and enforce policies.  

Who uses internal developer portals? 

Below are some examples of how different personas use internal developer portals. 

Developers

  • Get visibility and an understanding of everything  software, its dependencies, APIs, CI/CD, documentation, and more. 
  • Have more time to code  with self-service actions that let them autonomously create services, and perform day 2 operations, get temporary permissions and set up ephemeral environments,
  • Ensure standards compliance when services are scaffolded, and get notified when standards degrade, with clear paths to remediation. rity compliance with pre-configured actions.

Engineering leaders

  • Set standards and track compliance. Using scorecards, managers can make sure standards are communicated and monitored across all software assets.
    Scorecards can tackle anything from production readiness, ownership, security and cloud costs. 
  • Measure the performance of their team. The portal consolidates all engineering metrics and allows leaders to see them in context. For example, they can detect that a decrease in deployment frequency happens at the same time as a spike in incidents. In addition, if a key metric drops, engineering leaders can quickly assess the impact and find the answers to questions such as: Is it affecting customers? What product line is impacted? 

Managers

  • Ensure standards compliance by tracking scorecards and dashboards.
  • Gain visibility into team initiatives and improve productivity by managing sprints, tasks, and priorities efficiently.
  • Jumpstart engineering initiatives with tracking dashboards and approve requests quickly.

Security

  • Speed up the identification and prioritization of CVEs and security issues across all stages of the SDLC.
  • Ensure services meet security standards before production by combining checks from multiple tools and determining remediation responsibilities.
  • Drive initiatives when standards degrade.

Product Managers

  • Simplify feature flag management and streamline API understanding with an organized catalog.
  • Efficiently provision new environments for testing features and conduct effective demos.

SREs

  • Prevent incidents by using maturity scorecards, performance dashboards, and a centralized view for on-call engineers.
  • Improve production readiness and automate runbooks to handle recurrent issues and future-proof operations.

What are the top use cases for an internal developer portal? 

The following use cases are the top use cases that we’ve found when we asked our customers what they were using the portal for:

  1. ‍Discoverability and context: Create a comprehensive software catalog encompassing all company resources, from CI/CD metadata to cloud services and Kubernetes, helping developers locate what they need and minimize unnecessary duplication.
  2. ‍Driving organizational standards: Utilize scorecards to define clear standards for any entity within the software catalog, ensuring production readiness, code quality, migration quality, operational performance, and more.
  3. ‍Shipping faster to production: Enable developer self-service to grant developers autonomy in performing routine tasks, such as spinning up new microservices or creating ephemeral environments, without relying on other teams.
  4. ‍API governance: Enrich API metadata in the software catalog to provide context and structured performance feedback. Facilitate API scaffolding via self-service and use scorecards to ensure API quality and compliance, while tracking governance improvements.‍
  5. Simplifying Kubernetes for developers: Abstract Kubernetes complexity through self-service actions and software catalog information, allowing developers to work autonomously without needing in-depth K8s knowledge.‍
  6. Reducing mean time to recovery (MTTR): Utilize the portal for incident management by providing context and automating runbooks. Grant temporary permissions to on-call personnel through the portal for faster incident resolution.
  7. Migrations: Ensure the migration of deprecated versions by using the software catalog to keep services, APIs, and packages up-to-date with the latest version.‍
  8. Engineering metrics and insights: Leverage the data in the software catalog to generate reports and dashboards on engineering metrics, including DORA metrics, to provide valuable insights to managers.‍
  9. Optimizing and contextualizing cloud costs: Import and associate resources with their costs in the software catalog. Provide engineering management with dashboards containing cost information to drive initiatives aimed at reducing cloud costs.‍
  10. Optimizing and contextualizing cloud costs: Import and associate resources with their costs in the software catalog. Provide engineering management with dashboards containing cost information to drive initiatives aimed at reducing cloud costs.‍
  11. Managing feature flags: Use the software catalog to provide context and enable self-service actions for toggling feature flags on or off as needed.

What are the benefits of an internal developer portal?

  • Effective planning and bottleneck identification
    • Dashboards display relevant information from the software catalog, scorecards, and self-service actions, helping users plan their tasks. For example, developers can manage PRs, Jira tickets, on-call shifts, and security issues.
    • Managers can quickly approve requests, track initiatives, and identify bottlenecks or teams causing delays.
    • Developers receive alerts in context with necessary information, aiding in prioritizing and managing incidents effectively.

  • Speeding up developer onboarding
    • The software catalog provides insights into the tech stack, ownership, dependencies, reducing reliance on tribal knowledge.
    • Self-service actions minimize waiting times for access to tools, such as getting cloud resource permissions or creating environments.
    • Personalized dashboards display resources, key metrics, and onboarding documentation, improving time to first commit.

  • Lower MTTR
    • A centralized hub with integrated data from services, APIs, CI/CD, and incident management tools enhances incident response efficiency.
    • SREs can create incident management frameworks, scorecards, and self-service actions for on-call engineers.
    • During an incident, developers use self-service actions for temporary permissions and runbooks, and the software catalog provides them with context and ownership information related to the issue at hand.

  • Higher productivity
    • Centralizing tools and providing self-service capabilities streamline developer workflows and drive better outcomes.
    • Self-service actions throughout the SDLC, from planning to production, reduce total cycle time, improve standards, and enhance key metrics.
    • Dashboards in the portal measure the impact on SDLC, PR review times, and DORA metrics.

  • Enhancing the developer experience
    • A portal improves developer experience by replacing manual processes, providing a centralized view of assets, and reducing cognitive load.
    • Self-service actions and automations reduce wait times and improve feedback loops.
    • Customizable dashboards ensure developers have easy access to necessary information.

  • Increasing developer efficiency
    • A centralized platform for managing tasks, tools, and resources improves developer efficiency.
    • Self-service actions and automations streamline workflows, reduce context switching, and speed up tasks like scaffolding new microservices.
    • Manager dashboards track and measure developer efficiency against benchmarks.

  • Higher security, compliance, and governance standards
    • The software catalog provides visibility of software assets, with scorecards grading code quality, migration quality, and operational performance.
    • Developers can request temporary exceptions, and managers can track compliance with standards through a central view.
    • Automated alerts and self-service actions help maintain and improve production readiness.

  • Better managing production readiness
    • An internal developer portal balances speed and thorough checks by tiering services, associating assets with standards, and tracking compliance.
    • Automated tasks and self-service actions enable quick reactions to issues.
    • Initiatives track team progress towards new standards, enhancing production reliability.

  • Higher engineering velocity
    • Centralizing tools, data, and workflows in a portal reduces context-switching and streamlines resource access, boosting engineering velocity.
    • Integration across the development lifecycle allows quick access to information, task automation, and consistency.
    • Self-service capabilities accelerate the development process, enhancing productivity.

  • Reduced and controlled costs
    • Consolidating cost data in the portal shows connections to domains, applications, and services, aiding cost management.
    • FinOps use the portal to set cost standards and guardrails, helping developers understand service costs.
    • Managers can identify big spenders, set alerts for budget thresholds, and manage ephemeral environments effectively.
  • Pave golden paths
    • By centralizing tools, documentation, and self-service actions that have standards baked in, the portal ensures developers can easily access and follow these golden paths, reducing friction and cognitive load. This consistency helps maintain high standards, accelerates onboarding, and minimizes errors.
    • Standards of existing resources are monitored using scorecards, and any ‘bad’ resources can revert back to the golden path with day-2 operations self-service actions (eg. updating an outdated RDS cluster version). 

How do you get started with an internal developer portal? 

There are a number of things you can do to get started with an internal developer portal. Here is a list of resources we think can help you:

Previous article

Next article

{{cta_1}}

Check out Port's pre-populated demo and see what it's all about.

Check live demo

No email required

{{cta_2}}

Contact sales for a technical product walkthrough

Let’s start
{{cta_3}}

Open a free Port account. No credit card required

Let’s start
{{cta_4}}

Watch Port live coding videos - setting up an internal developer portal & platform

Let’s start
{{cta_5}}

Check out Port's pre-populated demo and see what it's all about.

(no email required)

Let’s start
{{cta_6}}

Contact sales for a technical product walkthrough

Let’s start
{{cta_7}}

Open a free Port account. No credit card required

Let’s start
{{cta_8}}

Watch Port live coding videos - setting up an internal developer portal & platform

Let’s start
{{cta-demo-baner}}

Book a demo right now to check out Port's developer portal yourself

{{port-for-backstage}}

Apply to join the Beta for Port's new Backstage plugin

Apply for beta
{{jenkins}}

It's a Trap - Jenkins as Self service UI

Read more
{{gitops}}

How do GitOps affect developer experience?

Read more
{{ebook}}

It's a Trap - Jenkins as Self service UI. Click her to download the eBook

Download eBook
{{cyberark}}

Learning from CyberArk - building an internal developer platform in-house

Read more
{{cta-demo}}
{{reading-box-backstage-vs-port}}

Further reading:

Read: What are the technical disadvantages of Backstage?

Compare: Backstage vs. Port

Example JSON block

{
  "foo": "bar"
}

Order Domain

{
  "properties": {},
  "relations": {},
  "title": "Orders",
  "identifier": "Orders"
}

Cart System

{
  "properties": {},
  "relations": {
    "domain": "Orders"
  },
  "identifier": "Cart",
  "title": "Cart"
}

Products System

{
  "properties": {},
  "relations": {
    "domain": "Orders"
  },
  "identifier": "Products",
  "title": "Products"
}

Cart Resource

{
  "properties": {
    "type": "postgress"
  },
  "relations": {},
  "icon": "GPU",
  "title": "Cart SQL database",
  "identifier": "cart-sql-sb"
}

Cart API

{
 "identifier": "CartAPI",
 "title": "Cart API",
 "blueprint": "API",
 "properties": {
   "type": "Open API"
 },
 "relations": {
   "provider": "CartService"
 },
 "icon": "Link"
}

Core Kafka Library

{
  "properties": {
    "type": "library"
  },
  "relations": {
    "system": "Cart"
  },
  "title": "Core Kafka Library",
  "identifier": "CoreKafkaLibrary"
}

Core Payment Library

{
  "properties": {
    "type": "library"
  },
  "relations": {
    "system": "Cart"
  },
  "title": "Core Payment Library",
  "identifier": "CorePaymentLibrary"
}

Cart Service JSON

{
 "identifier": "CartService",
 "title": "Cart Service",
 "blueprint": "Component",
 "properties": {
   "type": "service"
 },
 "relations": {
   "system": "Cart",
   "resources": [
     "cart-sql-sb"
   ],
   "consumesApi": [],
   "components": [
     "CorePaymentLibrary",
     "CoreKafkaLibrary"
   ]
 },
 "icon": "Cloud"
}

Products Service JSON

{
  "identifier": "ProductsService",
  "title": "Products Service",
  "blueprint": "Component",
  "properties": {
    "type": "service"
  },
  "relations": {
    "system": "Products",
    "consumesApi": [
      "CartAPI"
    ],
    "components": []
  }
}

Component Blueprint

{
 "identifier": "Component",
 "title": "Component",
 "icon": "Cloud",
 "schema": {
   "properties": {
     "type": {
       "enum": [
         "service",
         "library"
       ],
       "icon": "Docs",
       "type": "string",
       "enumColors": {
         "service": "blue",
         "library": "green"
       }
     }
   },
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {
   "system": {
     "target": "System",
     "required": false,
     "many": false
   },
   "resources": {
     "target": "Resource",
     "required": false,
     "many": true
   },
   "consumesApi": {
     "target": "API",
     "required": false,
     "many": true
   },
   "components": {
     "target": "Component",
     "required": false,
     "many": true
   },
   "providesApi": {
     "target": "API",
     "required": false,
     "many": false
   }
 }
}

Resource Blueprint

{
 “identifier”: “Resource”,
 “title”: “Resource”,
 “icon”: “DevopsTool”,
 “schema”: {
   “properties”: {
     “type”: {
       “enum”: [
         “postgress”,
         “kafka-topic”,
         “rabbit-queue”,
         “s3-bucket”
       ],
       “icon”: “Docs”,
       “type”: “string”
     }
   },
   “required”: []
 },
 “mirrorProperties”: {},
 “formulaProperties”: {},
 “calculationProperties”: {},
 “relations”: {}
}

API Blueprint

{
 "identifier": "API",
 "title": "API",
 "icon": "Link",
 "schema": {
   "properties": {
     "type": {
       "type": "string",
       "enum": [
         "Open API",
         "grpc"
       ]
     }
   },
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {
   "provider": {
     "target": "Component",
     "required": true,
     "many": false
   }
 }
}

Domain Blueprint

{
 "identifier": "Domain",
 "title": "Domain",
 "icon": "Server",
 "schema": {
   "properties": {},
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {}
}

System Blueprint

{
 "identifier": "System",
 "title": "System",
 "icon": "DevopsTool",
 "schema": {
   "properties": {},
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {
   "domain": {
     "target": "Domain",
     "required": true,
     "many": false
   }
 }
}
{{tabel-1}}

Microservices SDLC

  • Scaffold a new microservice

  • Deploy (canary or blue-green)

  • Feature flagging

  • Revert

  • Lock deployments

  • Add Secret

  • Force merge pull request (skip tests on crises)

  • Add environment variable to service

  • Add IaC to the service

  • Upgrade package version

Development environments

  • Spin up a developer environment for 5 days

  • ETL mock data to environment

  • Invite developer to the environment

  • Extend TTL by 3 days

Cloud resources

  • Provision a cloud resource

  • Modify a cloud resource

  • Get permissions to access cloud resource

SRE actions

  • Update pod count

  • Update auto-scaling group

  • Execute incident response runbook automation

Data Engineering

  • Add / Remove / Update Column to table

  • Run Airflow DAG

  • Duplicate table

Backoffice

  • Change customer configuration

  • Update customer software version

  • Upgrade - Downgrade plan tier

  • Create - Delete customer

Machine learning actions

  • Train model

  • Pre-process dataset

  • Deploy

  • A/B testing traffic route

  • Revert

  • Spin up remote Jupyter notebook

{{tabel-2}}

Engineering tools

  • Observability

  • Tasks management

  • CI/CD

  • On-Call management

  • Troubleshooting tools

  • DevSecOps

  • Runbooks

Infrastructure

  • Cloud Resources

  • K8S

  • Containers & Serverless

  • IaC

  • Databases

  • Environments

  • Regions

Software and more

  • Microservices

  • Docker Images

  • Docs

  • APIs

  • 3rd parties

  • Runbooks

  • Cron jobs

You may also be interested in

Building the perfect internal developer platform

Building the perfect internal developer platform

Read more
How to use JQ commands to speed developer workflows

How to use JQ commands to speed developer workflows

Read more
Debugging K8s with K8sGPT in your internal developer portal

Debugging K8s with K8sGPT in your internal developer portal

Read more

Starting with Port is simple, fast and free.

Let’s start