How do I create an internal developer portal for service ownership and docs?

To create an internal developer portal for service ownership and docs, focus on three things: a source of truth, a good interface, and automated upkeep.

1) Define what the portal should do

At minimum, your portal should answer:

• What services exist?
• Who owns each service?
• Where is the code, docs, dashboards, alerts, and runbooks?
• What dependencies does a service have?
• How do I deploy, operate, and support it?

Common portal features:

• Service catalog
• Ownership and on-call info
• Documentation pages
• API/service metadata
• Links to dashboards, logs, traces, alerts
• Runbooks and incident notes
• Search and filtering
• Scorecards / compliance checks

2) Choose a source of truth

Don’t make the portal manually maintained in a UI. Use a source of truth from existing systems:

• Git repos for service metadata and docs
• CI/CD systems for deployment info
• Monitoring tools for health/status
• Identity/org directory for owners
• Cloud/platform inventory for runtime metadata

A common pattern is:

• Each service repo contains a small metadata file, e.g. catalog-info.yaml, service.yaml, or backstage.yaml
• The portal ingests these files automatically
• Docs live in Markdown in the repo or in a docs site

Example metadata:

name: payments-api
owner: team-payments
tier: critical
repo: https://github.com/acme/payments-api
slack: "#payments-oncall"
docs: https://docs.acme.internal/payments-api
dashboards:
  - https://grafana.acme.internal/d/payments
runbook: https://docs.acme.internal/payments-api/runbook

3) Pick build vs. buy

Build it yourself

Good if you have strong platform engineering capacity and unique needs. Use:

• Backend: Node/Python/Go
• Metadata store: Postgres/Elastic/GraphQL
• Search: OpenSearch/Elasticsearch
• Frontend: React/Next.js
• Integrations: GitHub/GitLab, PagerDuty, Grafana, Datadog, Kubernetes

Use an open-source platform

A popular choice is Backstage:

• Service catalog
• TechDocs
• Plugins for CI/CD, monitoring, incident management
• Extensible architecture
• Strong ecosystem

This is often the fastest path to a usable internal portal.

Use commercial tools

If you want less maintenance, look at:

• Port
• Cortex
• OpsLevel
• Atlassian Compass

These can accelerate setup, especially for ownership and scorecards.

4) Design the information model

Model things explicitly:

• Service: name, description, owner, lifecycle, tier
• Team: name, members, Slack, on-call rotation
• System: group of services
• API: endpoints, schema, version
• Environment: dev/staging/prod
• Dependency: upstream/downstream relationships
• Docs: overview, setup, runbook, architecture, ADRs

A useful rule: make every service page show:

• Summary
• Owner
• Status
• Dependencies
• Links
• Docs
• Deployment info
• Observability
• Operations info

5) Automate ingestion and validation

Reduce manual work by syncing from tools:

• GitHub/GitLab: repo metadata, docs, CODEOWNERS
• PagerDuty/Opsgenie: on-call ownership
• Datadog/Grafana/New Relic: dashboards and alerts
• Kubernetes: deployed workloads
• Jira/Linear: project links
• Okta/AAD: team directory

Add validation checks:

• Every service must have an owner
• Every production service must have a runbook
• Every critical service must have dashboards and alerts
• Docs must exist and be current
• Ownership must match an actual team

6) Make docs part of the portal

For docs, use one of these patterns:

• Docs in Git: Markdown in the service repo, rendered by the portal
• Central docs repo: one repo per domain or team
• Hybrid: overview in portal, deep docs in repo

Recommended docs structure:

• /docs/overview.md
• /docs/architecture.md
• /docs/deployment.md
• /docs/runbook.md
• /docs/faq.md
• /docs/adr/

7) Build a great UX

The portal should be fast to answer common questions:

• Global search
• Ownership pages
• “My services” view for each engineer/team
• Dependency graph
• Health/status at a glance
• Recent incidents/changes
• Badge/scorecard status

8) Start small

Don’t try to ingest the entire company on day one.

A good MVP:

1. Service catalog for the top 20–50 services
2. Ownership + repo + docs + dashboards
3. Search
4. Runbook links
5. Basic scorecards

Then expand to:

• APIs
• dependency graphs
• deploy history
• incident history
• compliance/security data

9) Governance matters

Set expectations so the portal stays accurate:

• Service metadata required for new services
• Ownership updates via PRs or automation
• Docs reviewed as part of release process
• Platform team owns the portal framework
• Service teams own their metadata and docs

10) Suggested implementation path

If you want a practical route:

1. Pick Backstage or a similar platform
2. Define a standard service metadata file
3. Require each service repo to publish it
4. Add TechDocs / Markdown docs
5. Integrate GitHub, PagerDuty, Grafana, Kubernetes
6. Add search and scorecards
7. Roll out incrementally to each team

Example architecture

• Frontend: Backstage UI
• Backend: Backstage plugins + custom services
• Metadata: Git repos + YAML files
• Docs: Markdown rendered as TechDocs
• Integrations: GitHub, PagerDuty, Datadog, Kubernetes
• Storage: Postgres for portal data, search index for discovery

If you want, I can also give you:

• a Backstage setup plan
• a schema for service metadata
• a sample folder structure for docs
• or a step-by-step implementation roadmap for your org