How to Create a Service Catalog in Confluence
A service catalog is the engineering team's directory of what they run. It answers the questions that slow down incident response and onboarding: who owns this service, what does it depend on, where are the runbooks, and what SLAs does it carry? Without a catalog, these answers live in people's heads — and leave with them.
This guide covers how to build a service catalog in Confluence that engineering teams actually maintain: structured service pages, an ownership table, a dependency visualization, and a quarterly review process.
Step-by-step guide
Set up the Service Catalog Confluence structure
Create a Confluence space (or top-level page in your Engineering space) called "Service Catalog." Create two sections: Services (one page per service) and Infrastructure (shared databases, message queues, caches). On the Service Catalog home page, embed a Page Properties Report macro listing all service pages with their key properties — this auto-generates a catalog table without manual maintenance. Add the Service Catalog to your Confluence space shortcuts so it appears in the sidebar.
Define the service page template
Create a Confluence page template called "Service" with these sections: Service Overview table (Service Name, Team Owner, Primary On-Call, SLA Tier, Status: Active/Deprecated), Description (one paragraph — what the service does, who consumes it, and why it exists), Repository (link to the GitHub repo), Deployment (how the service deploys — CI/CD pipeline, deployment frequency, rollback procedure), Dependencies (table: Service/System, Type: Upstream/Downstream, Criticality), Runbooks (links to relevant runbooks), Alerting (links to PagerDuty alerts or monitoring dashboards), Known Limitations (anything engineering and consumers should know), and Last Reviewed (date the page was last audited).
Build the service dependency map
For each service page, create a dependency table: Service, Type (upstream = this service depends on it, downstream = it depends on this service), Criticality (hard dependency vs. graceful degradation if unavailable), and SLA Impact (if this dependency is down, what is the customer impact?). On the Service Catalog home page, embed an architecture diagram (Confluence Draw.io or linked Figma file) showing all services and their dependencies visually. The table is the queryable data; the diagram is the mental model.
Establish ownership and on-call coverage
Every service in the catalog must have a Team Owner (the team responsible) and a Primary On-Call (the specific engineer who is currently on-call). Use the Confluence Team Mention or Person macro to reference these — they auto-update when the person's Confluence profile changes. Create a view of the catalog filtered to services without a Primary On-Call assigned — this is your coverage gap report. Any service with no on-call is a reliability risk.
Set up the quarterly catalog review
Add a quarterly "Service Catalog Review" to the engineering calendar. In each review: open the Service Catalog home page, filter for pages with Last Reviewed older than 90 days, assign each stale page to its Team Owner to review and update, and check for services that are deprecated but still listed as Active. The review takes 2 hours for the whole team and keeps the catalog as a living resource rather than a snapshot from the last all-hands.
Common mistakes
Service catalog that duplicates information from code
The service catalog is not a README duplication layer. READMEs belong in the repository. The catalog provides the cross-service view that the repository cannot: ownership, dependencies on other services, on-call contacts, and SLA tier. Keep the catalog focused on operational metadata — not implementation details.
No ownership for internal shared services
Databases, message queues, and shared caches are often listed in the catalog without a team owner because "everyone uses them." Assign ownership even for shared infrastructure: one team owns the Postgres cluster (responsible for upgrades, capacity, and incident response). Everyone else is a consumer. Unclear ownership for critical shared infrastructure is a single point of failure in incident response.
Catalog only populated at launch and never updated
A service catalog written during an engineering offsite and never touched again is an archaeological artifact. Add catalog updates to the definition of done for any change that affects service ownership, dependencies, or SLAs. When a new service is created, the catalog page is created before the service goes to production. When a service is deprecated, its Status is updated the same day.
Tips
Use the Confluence Page Properties macro on every service page and a Page Properties Report on the home page — the report auto-generates a table of all services with their Owner, SLA Tier, and Last Reviewed date without any manual maintenance. The table stays current as long as service pages use the Page Properties macro.
Create a Confluence label "service-catalog-entry" and apply it to every service page — this allows engineers to find all catalog entries with a single label search even if the page hierarchy is reorganized
Embed the service catalog home page in your on-call Slack channel's topic and in your incident response runbooks — during an incident, the first thing an engineer needs is "who owns this service?" The catalog answers that in one click
How Vantage helps
A service catalog documents what engineering runs. Vantage connects service catalog data to product planning: when a PM is writing a PRD for a new feature, Vantage can surface the relevant services from your Confluence catalog and their on-call contacts — so the PRD includes the right engineering stakeholders and the ticket generation produces work items for the correct teams.