Do You Need an Internal Developer Portal Under 50 Engineers?

It answers questions that otherwise get asked in chat repeatedly:

• Who owns this service, and how do I reach them or their on-call?
• Where's the runbook, the dashboard and the deployment pipeline?
• What does this service depend on, and what depends on it?
• How do I create a new service with the right defaults?
• Which services fail our reliability, security or documentation standards?

Notice that the first three are catalog problems, and they're the ones small teams feel first. Software templates and scorecards come later, when you have enough services that consistency slips.

Look for evidence, not a feeling. You're probably ready when several of these are true:

• New engineers regularly need days to find the right repo, owner or environment.
• During incidents, people spend minutes working out who owns a failing service.
• You have more services than anyone can name from memory, and some have no clear owner.
• Every team documents in a different place, and the docs are stale.
• You've had a security or compliance request that needed a list of services and owners, and building it took a week.
• Setting up a new service takes copy-paste from an old one, and each copy drifts.

If none of these hurt yet, you're likely early. Note that team count matters more than headcount: three squads with ten services each feel this pain sooner than one team with fifty.

Try these low-cost steps first, and you'll learn what a portal would need to hold anyway:

1. Add a metadata file to every repository listing owner, on-call channel, tier, runbook link and dashboard link. A short list of required fields, covering owner, tier, on-call and runbook, is enough.
2. Adopt a README structure that every service follows, with a "how to run it" and "how to deploy it" section.
3. Publish a single index page or spreadsheet built from those metadata files by a scheduled script.
4. Write a repository template that new services start from.
5. Add a CI check that fails when the metadata file is missing or has an empty owner.

Say you have 25 engineers and 30 services. That setup takes a few days and covers most of what you'd get from a portal's catalog.

When you do outgrow the basics, you have three paths. Backstage is an open-source framework: it's flexible and free to license, but it needs engineers who can maintain a custom application and its plugins, which is a serious commitment for a small team. Hosted products such as Port and Cortex reduce that operating burden and get you a working catalog sooner, at a subscription cost, with less freedom to customize.

Before choosing, ask how much platform engineering time you can dedicate, which integrations matter (source control, incident tooling, cloud accounts), and how the data will stay fresh. Confirm pricing and current capabilities with each vendor. The portal comparison goes through the criteria in more detail.

Portals fail through stale data, not missing features. To avoid it:

• Launch with the catalog only: services, owners, links. Skip scorecards and templates for the first quarter.
• Derive data from source of truth, such as repository metadata and cloud tags, rather than asking people to type it twice.
• Assign a product owner for the portal, even part time, with a small backlog.
• Pick one team problem to fix in the first month, such as incident ownership lookup, and measure whether it improved.
• Retire what nobody uses. If the portal isn't the first place people look, it isn't helping.

Connect it to your reliability work with an SLO per service and track delivery health with DORA metrics so the portal answers real questions.