Skip to content

Port (Internal Developer Portal)

Scope

This file covers Port as an internal developer portal (IDP): the software catalog data model (blueprints, entities, relations, mirror and calculation properties), data ingestion via the Ocean integration framework and its Port-hosted vs self-hosted installation modes, JQ mapping configuration, scorecards and levels for standards enforcement, self-service actions and their backends, automations, RBAC and dynamic permissions, SaaS deployment posture and data residency, and the buy-vs-build decision against Backstage. It also covers the failure mode that decides most IDP programs — catalog freshness and ownership — which is organizational rather than technical.

For the request-and-approval storefront pattern that overlaps with IDP self-service, see patterns/servicenow-catalog-finops-design.md and providers/servicenow/itsm.md; those solve a different problem (a governed request catalog for IT services) and the distinction is an ADR trigger below. For CI/CD and repository concerns that an IDP catalogs rather than replaces, see providers/github/ and providers/gitlab/. For the change-record boundary, see general/change-management.md.

Checklist

  • [Critical] Is the catalog's source of truth decided before any blueprint is drawn -- which system owns each fact (Git for ownership, the cloud API for infrastructure, the IdP for people), and is Port modeling those systems or becoming a fourth place someone types a service name? (An IDP that holds facts nobody else holds is a system of record with no upstream, and it decays the moment its author leaves.)
  • [Critical] Is the blueprint model sized to the questions being asked -- how many blueprints, which relations between them, and what specific question does each relation answer? (Port's data model is user-defined rather than fixed; that is its advantage over Backstage's Component/System/API kinds and also its main failure mode, because an over-modeled catalog is unmaintainable and an under-modeled one cannot answer the question that justified buying it.)
  • [Critical] How does data get in, and what runs where -- Ocean integrations hosted by Port, Ocean self-hosted inside the network, webhook push, or direct API writes from CI? (Self-hosted is the answer when the source system is not internet-reachable or when the source's rate limits need tuning; Port-hosted is the answer otherwise and removes a service to operate.)
  • [Critical] Is catalog freshness measured and owned -- what is the resync interval per integration, what happens when an integration fails silently, and is there an alert on staleness rather than only on error? (A stale catalog is worse than no catalog, because it is trusted. This is the single most common reason IDP programs quietly die.)
  • [Critical] Are self-service actions mapped to an execution backend with the right blast radius -- GitHub workflow, GitLab pipeline, webhook to an internal service, or Port-run automation -- and does the action run with its own scoped credentials rather than a human's? (An action that provisions infrastructure is a privileged path with a form in front of it; the form is not the control, the backend's credentials are.)
  • [Recommended] Is the scorecard model defined with levels that mean something -- Port's default Basic/Bronze/Silver/Gold, or custom levels, with rules whose failure a team can actually act on this sprint? (An entity advances a level only by passing all rules at that level, so one unachievable rule pins every service below it and the scorecard stops being read.)
  • [Recommended] Is there agreement on what scorecards are for -- surfacing gaps to the owning team, or reporting maturity upward to management? (These produce different rule sets and different politics; a scorecard used for performance review gets gamed, and the gaming is cheaper than the fix.)
  • [Recommended] Is the JQ mapping for each integration under version control and reviewed, rather than edited in the UI? (Mappings are the schema translation layer; an unreviewed UI edit is an undocumented change to what every downstream scorecard and action sees.)
  • [Recommended] Is RBAC designed around who may run actions rather than who may see the catalog -- and does the plan tier include what the design assumes? (SSO and dynamic permissions arrive at Standard; SCIM provisioning, IP allowlisting and Private Link are Enterprise, verified 2026-08-05.)
  • [Recommended] Is the data residency requirement checked against the available regions -- Port is SaaS on AWS with separate EU and US API endpoints (api.port.io and api.us.port.io), with dedicated tenancy and Private Link offered to Enterprise? (There is no customer-hosted control plane; if the requirement is "no third party holds our service metadata", Port is the wrong product and Backstage is the honest alternative.)
  • [Recommended] Are automations distinguished from self-service actions in the design -- automations fire on catalog events (entity created, scorecard level dropped), actions are user-initiated? (Conflating them produces either a portal that does nothing without a human or a set of invisible side effects nobody can trace.)
  • [Optional] Is the entity count projected against plan limits, including entities created by ingestion rather than by hand? (Kubernetes and cloud-resource integrations generate entities at a rate the initial estimate rarely anticipates; Free is 10K, Basic 50K, Standard 250K, Enterprise 1M+, verified 2026-08-05.)
  • [Optional] Is there a rollback and export answer -- can the catalog definition (blueprints, scorecards, actions) be re-created from version-controlled source if the tenant is lost or the vendor is changed? (Terraform provider and API export exist; the question is whether anyone has exercised the restore.)
  • [Optional] Are Port AI and agent features evaluated against the data-handling posture the organization requires, including what catalog content is sent to model providers? (See the AI section below; treat this the same way providers/atlassian/itsm.md treats Atlassian Intelligence.)

Why This Matters

An internal developer portal fails organizationally far more often than technically, and the failure is always the same shape: the catalog goes stale, developers stop trusting it, and it becomes a dashboard nobody opens. Port's product answer to this is ingestion — Ocean integrations pull from the systems that already know the truth (Git providers, Kubernetes, cloud accounts, incident tools) rather than asking humans to maintain a registry. That answer only works if every blueprint traces to an upstream system that owns its facts. The moment a blueprint holds a field that only a human types and nothing validates, that field starts rotting, and a catalog with rotting fields is one bad experience away from being abandoned. The design question is therefore not "what do we want to see" but "what already knows this, and how does it get here."

The second consequential decision is buy-vs-build against Backstage, and it is not primarily about features. Backstage is a Spotify-originated open-source framework: it is a Node application the organization runs, extends with plugins, and upgrades. Its catalog model is fixed around Component, System, API, Resource and Group, which is a constraint that keeps small deployments coherent and frustrates larger ones. Port is SaaS with a user-defined blueprint model, so it starts faster and bends further, at the cost of a vendor holding service metadata and a per-seat bill that scales with the engineering organization. Teams that pick Backstage for cost frequently discover the real cost is a permanently staffed platform team maintaining a portal; teams that pick Port for speed sometimes discover a data-residency requirement they did not surface, because there is no customer-hosted control plane to fall back to. Establish the residency constraint before the evaluation, not after.

The third thing worth getting right early is scorecards. Port evaluates an entity against rules grouped into levels, and an entity advances only by passing every rule at a level. That is a deliberate design — partial credit produces meaningless scores — but it means one poorly chosen rule pins the entire estate at Basic and the scorecard becomes noise. Scorecards also change behavior in ways that depend entirely on who reads them: shown to an owning team as a gap list, they drive real remediation; reported upward as a maturity metric, they drive whatever is cheapest to satisfy. Decide the audience before writing the rules, and expect that decision to be contested.

Common Decisions (ADR Triggers)

  • Port vs Backstage -- Port is SaaS with a user-defined blueprint model, managed ingestion (Ocean), built-in scorecards and self-service actions, and a per-seat cost that grows with the engineering organization. Backstage is an open-source framework the organization hosts and extends, with a fixed catalog model, a plugin ecosystem, and a cost that is mostly the platform engineers who maintain it. Choose Port when time-to-value matters and the catalog model does not fit Component/System/API cleanly; choose Backstage when service metadata may not leave the organization, when deep custom UI is required, or when a platform team already exists and wants to own the surface. Cost comparisons that count only license fees are misleading in both directions. Argued from the build side in providers/backstage/software-catalog.md, which also prices the commercial Backstage distributions that sit between the two.
  • Port vs ServiceNow Service Catalog -- These look adjacent and solve different problems. ServiceNow's catalog is a governed request-and-approval storefront with ITSM, CMDB and financial management behind it; Port's is a developer-facing software catalog whose actions run pipelines. Organizations with both should decide which one owns infrastructure requests specifically, because that is where they overlap and where two answers means neither is trusted. See patterns/servicenow-catalog-finops-design.md.
  • Do we need an IDP at all -- The honest alternative for a small estate is a well-maintained README index and a Jira project, and it is frequently the right answer. An IDP earns its keep when the number of services exceeds what any one person can hold, when onboarding time is a measured problem, or when standards need to be visible per-service rather than asserted org-wide. Buying one to create platform discipline rather than to scale existing discipline is the common expensive mistake.
  • Ocean hosted by Port vs self-hosted -- Port-hosted removes a service to run and is the default. Self-hosted is required when the source system is not reachable from the internet, and is preferable when the source's rate limits need tuning or when the integration's egress must be controlled. The choice is per-integration, not global, and mixing them is normal.
  • Catalog scope: services only vs everything -- A catalog limited to deployable services stays accurate cheaply. Extending it to cloud resources, Kubernetes objects, packages and teams produces a far more useful graph and a much larger freshness obligation, and it is what consumes entity-count allowance. Decide the boundary explicitly and revisit it, rather than letting integrations expand it by default.
  • Scorecards as gap list vs maturity metric -- The same feature, two incompatible social contracts. A gap list shown to owning teams drives remediation; a maturity metric reported upward drives optimization toward the metric. Pick one, say which, and set expectations with leadership before the first scorecard ships.
  • Self-service action execution backend -- Running actions as GitHub/GitLab pipelines keeps the audit trail and permissions in the system engineers already use, at the cost of pipeline sprawl. Running them as webhooks to an internal service centralizes control at the cost of building and operating that service. The deciding question is where the privileged credentials should live.
  • Data residency and tenancy -- Port is SaaS on AWS with EU and US endpoints, and offers dedicated tenancy plus Private Link to Enterprise customers. If the requirement is that no third party holds service metadata at all, that is a disqualifying constraint rather than a configuration, and it should be established before evaluation rather than discovered during procurement.

AI and GenAI Capabilities

Port's documentation is currently organized around a Context Lake (the unified catalog data layer), Port AI (natural-language interaction with catalog data), and Agent Management (orchestration of custom agents), alongside the Interface Builder and Governance Layer. The architectural argument is that a well-maintained software catalog is exactly the grounded context an agent needs to answer questions about an estate — which is a real advantage over asking a model to reason about infrastructure from documentation alone.

Two things to establish before enabling it, for the same reasons providers/atlassian/itsm.md raises about Atlassian Intelligence: what catalog content is sent to model providers, and whether that is compatible with the residency posture chosen above. A catalog rich enough to be useful to an agent is also rich enough to describe the estate in detail. Verify current data-handling terms directly with the vendor rather than from this file; this area is moving faster than any knowledge file's review cycle.

See Also

  • providers/backstage/software-catalog.md -- the build side of the same decision: the fixed entity model, the descriptor-in-repo catalog, and the upgrade burden that is the real cost
  • providers/servicenow/itsm.md -- the governed request-catalog alternative, and the overlap to arbitrate
  • patterns/servicenow-catalog-finops-design.md -- request-time UX and cost presentation for a service catalog
  • providers/vmware/aria-suite.md -- frames the same buy-vs-build question from the VCF Automation side, naming Backstage as the build option
  • general/change-management.md -- where the change record lives when self-service actions perform changes
  • providers/github/ and providers/gitlab/ -- the systems an IDP catalogs and executes through, rather than replaces
  • Port documentation -- Context Lake, Workflows & Tools, Port AI, Governance Layer, Interface Builder, Platform Administration
  • Scorecards: concepts and structure -- rules, levels (Basic/Bronze/Silver/Gold by default), filters, and the all-rules-at-a-level progression semantics
  • Ocean custom integration overview -- the integration framework and the YAML/JQ mapping model
  • Ocean: hosted by Port -- the managed installation mode and resync interval
  • Port security and compliance -- AWS hosting, EU/US API endpoints, dedicated tenancy and Private Link for Enterprise
  • Port pricing -- Free / Basic / Standard / Enterprise, seat and entity limits, and which tier gates SSO, SCIM, IP allowlisting and Private Link
  • Backstage -- the open-source alternative and the other half of the buy-vs-build ADR; see providers/backstage/software-catalog.md