The acronym IDP does a lot of heavy lifting in platform engineering circles. Ask ten people what it stands for, and you’ll typically get two answers: internal developer platform and internal developer portal. Maybe even a rogue Identity Provider just for fun, too! But seriously, same letters, very different things, and it matters more than it might seem.
A portal is the interface. It’s where a developer logs in and finds everything they need in one place, including services, pipelines, documentation, logging, observability, and ownership. They don’t necessarily need to know which tool sits behind each action, or who to ask for access. It’s a genuinely compelling end state. But it’s just that — an end state.
I see and hear about many teams trying to build the GPS before the roads exist.
A GPS is an incredible tool. It gets you where you’re going, surfaces the best route, and removes the guesswork. But if the roads aren’t there, or if they’re unpaved, inconsistently maintained, or only connected in some places, the GPS doesn’t fix that. It just navigates you into a field with more confidence, resulting in a poor user experience. The same is true of a portal sitting on top of a platform that isn’t ready to support it.
Portals have real value. But so does sequencing. Get the platform right first, and the portal becomes genuinely powerful. Rush to the portal before the foundations are solid, and you’re surfacing chaos through a clean UI.
When the portal becomes the platform team’s second job
I understand the appeal of a nice, polished developer portal. That single place where teams can go to self-service infrastructure, discover documentation, review application performance, all without filing a ticket or waiting on someone else. They provide a service catalogue, integrations across the tooling used in your platform, and get users to the desired golden paths fast.
One problem is the cost of getting to that point, and teams that don’t consider that cost and prioritize a portal before the underlying platform is ready for it can open themselves up for a world of pain. Portals are a product in their own right and will need to be either procured or built yourself, or a combination of the two. Whichever way you go, it’s going to require the usual care and feeding - engineering time, maintenance, new features and functionality, and one way or another, funding. That’s engineering time that isn’t going toward making the platform itself more reliable, more consistent, or easier to use.
I’ve spoken with Platform Engineers who have been asked to provision a portal for their platform, and go down a rabbit hole of open source solutions and evaluating commercial solutions, only to discover the portal itself is going to take more than a couple of hours a week to maintain, and that’s before you’ve written a single integration. The realization that a portal needs to be managed on top of the Platform itself is daunting to many Platform teams, who are already stretched thin.
A portal then also influences future Platform tooling choices. How hard is it to integrate new tooling with the portal? Does the new tool provide integrations or plugins out of the box, or does the platform team need to build and maintain them themselves?
The organizations that tend to get value from a dedicated portal are those operating at significant scale, with hundreds of developers and dozens of teams, and complex enough that the cost of running a portal becomes a rounding error compared to the coordination problems it solves. For most teams, that bar is higher than it looks. Are you there yet?
Start with solid foundations before you surface it
Good roads aren’t just tarmac. They have lane markings, speed limits, signs, and traffic lights. All of the things that make roads safe and predictable to navigate. A GPS doesn’t create any of that. It surfaces it. A portal works the same way. It can expose your golden paths, governance, pipelines, and self-service workflows, but it doesn’t define them for you. Get the road right first.
Your platform will consist of tens of tools, each focused on solving problems in its own domain. All of those tools can be configured and integrated in different ways to achieve the outcomes your teams need, and a lot of effort from Platform Engineering teams goes into making them work well together for the organization.
It’s also likely your developers and application teams have worked directly with the platform tools in their careers, too, and while context switching is an issue, it won’t be unfamiliar to them to move between different tools to get their work done. If you can lower the friction they have when working with the underlying platform tools, that’s a huge win, and in my opinion, it’s a signal of a successful platform foundation.
And with the rise of AI, that’s becoming even more relevant. Developers increasingly want to be met where they’re already working. That might be by providing a Command Line Interface, an API call, or an MCP server that the developer—or the agent they are using—can interact with directly. A well-structured platform exposes those interfaces. A portal is one way to surface platform capabilities, but it’s not the only way, and for many developers, it might not even be the preferred one.
You’re probably familiar with core concepts that platform teams focus on: standardization, policies and governance, self-service, and repeatable, consistent delivery across teams and environments. There’s a lot of work that goes into getting those foundations right before they are ready to be surfaced through an interface, and it doesn’t stop once they’re in place. The tools your platform is built on keep evolving. Vendors ship new features, integrations improve, and better primitives emerge. A good platform team takes advantage of that, pushing complexity back onto vendors and partners where possible, and reducing the volume of custom scripts and integrations they need to own and maintain themselves. The point is that building a platform isn’t a 12-month checkbox exercise. It’s a living thing that needs ongoing maintenance, care, and attention. New roads get built, old ones get resurfaced, and the rules of the road change over time. Your platform is no different. The tools keep evolving, your organization’s needs shift, and the work of keeping it solid never really stops.
Adding a portal to a platform will begin to expose the platform’s underlying capabilities as they stand today. If your underlying platform has a strong foundation and delivers measurable benefits to the organization, exposing its capabilities in a portal will amplify the value it already delivers, enabling developers to get faster access to what already works. But the same can be said if your underlying platform is a bit of a mess, too. A portal that surfaces an inconsistent or fragile deployment pipeline doesn’t hide the inconsistency. It just makes it more visible and more frustrating to more people.
A portal amplifies what’s already there. Make sure what’s already there is worth amplifying.
Portals have a place
When you’re working in an organization with hundreds of developers and many applications, finding the right information is hard. Even just knowing what you have in the organization can be a massive undertaking. Ask a new engineer at most organizations to find the logs for a service they didn’t build, and watch what happens. They’ll ask around, dig through wikis, search Slack, and probably end up messaging whoever seems like they might know. It works, eventually. But it shouldn’t be that hard.
Here at Octopus Deploy, where you could argue we have one core product, there are many Engineering teams, each owning different parts of the application. They all have defined software development processes, source code, internal and external documentation, and several Slack channels. Even though some of that information lives in the same tool across teams - let’s use GitHub as an example for our source code tool - there are still hundreds of repositories internally. There’s also the support and operational lens too, such as where the logs are being sent, what observability is being used by each application, where you file a bug or request a new feature, and who to contact or where to go if you need to ask a question from the team that owns the service.
Sit for a moment and ask these same questions in the context of your company, and consider how long it would take a new engineer on your team to find those answers on their own.
Service discoverability is one use case where a portal can deliver real value without a huge lift for the platform team. The information already exists in your organization; it just needs to be collated and surfaced in one place.
Once your platform foundations are solid, a portal can surface those capabilities in a way that genuinely changes how developers interact with it. Self-service workflows that are repeatable and reliable, golden paths that are well-defined and trusted, pipelines that behave consistently across teams and environments. A portal can bring all of that together in one place and make it accessible without developers needing to know what sits behind each action.
A useful question to ask yourself: if we built a portal today, what would we put in it? If the answer is “not much,” that’s a signal there’s more platform work to do first, or that your company doesn’t even need a portal to make the most of Platform Engineering. If the answer is a long list of capabilities that are already working well and delivering value, you’re probably ready.
This is where the GPS analogy comes full circle. The roads are built, the lane markings are down, and the signs are in place. Now you can hand people a GPS and trust that it will reliably navigate them to where they need to go, on the most efficient route. That’s the version of a portal worth building toward.
Roads first, GPS second. Where’s your team at?
A portal is a powerful navigation tool. But navigation only works when there’s somewhere real to go. Every organization is at a different point on this journey, and this post isn’t a rule book. Some teams genuinely are ready to invest in a portal, and for them, it will pay off. But in my experience, most teams have more platform work to do before the portal delivers on its promise.
The roads come first. The GPS comes when the roads are worth navigating.
So, where’s your team at?
Happy Deployments!
