Migrating From Confluence to a Developer Portal in 2026

Confluence-plus-spreadsheet is the most common pre-portal state. Migrating to a developer portal is a 3 to 6 month engagement that typically costs $80,000 to $200,000 of platform-engineer time. Here is a vendor-neutral breakdown of the work, the historic-page abandonment decision, and the redirect strategy that protects existing knowledge links.

Total migration cost

$80K-$200K

platform-team time, 3 to 6 months

Catalogue bootstrap

$20K-$50K

extracting service estate from Confluence

TechDocs migration

$20K-$80K

high-value service docs to markdown

The Pre-Migration State

Confluence-plus-spreadsheet is the most common pre-portal state for mid-sized engineering organisations. The pattern: a Confluence space for engineering with one page per service (some current, many stale), a separate spreadsheet maintained by someone in operations listing services with owners and runbook links (also often stale), runbooks stored partly in Confluence and partly in repository READMEs, on-call procedures stored in Confluence pages or in PagerDuty. Discovery happens through Slack-based questions and tribal knowledge; the documentation system is the safety net rather than the primary source.

Organisations migrate to a developer portal when this pattern breaks down. The Slack-based discovery becomes a real productivity drag (new engineers spend their first month asking who owns what), the spreadsheet of services becomes too stale to trust, the runbooks become impossible to find when an incident is in progress. The portal is the structural fix; the migration cost is the price of the fix.

Migration Phase Detail

Phase one is catalogue bootstrap. The work is extracting the service estate from Confluence into the portal's catalogue entity model. For each service, a portal catalogue entity has to be created with the canonical name, the owning team, the lifecycle stage, the relevant repository links, the on-call rotation, the runbook links, the dependency relationships. Most of this data exists in Confluence in unstructured form; extracting it requires either an automation pass against the Confluence API (faster but produces messy output that needs cleanup) or a manual walk-through with the owning teams (slower but produces clean output). Most organisations use a hybrid: automate the easy extraction, walk-through with teams for the cases the automation cannot handle. Typical cost: $20,000 to $50,000 of platform-team time.

Phase two is TechDocs migration for high-value service documentation. The work is converting Confluence pages to markdown that lives alongside service code, then publishing through the portal's documentation surface. Confluence-to-markdown conversion is partially automatable (Confluence has an API, several open-source converters exist) but has a manual review tail for content that does not convert cleanly (embedded macros, complex tables, page attachments). The cost varies with how many pages get migrated; the right discipline is to migrate selectively (the 20 to 50 percent of documentation that engineers actually consult). Typical cost: $20,000 to $80,000 of platform-team time, with the wide range reflecting how much content gets migrated.

Phase three is the redirect strategy. Confluence URLs are referenced across the engineering organisation in Slack messages, runbooks, on-call escalation procedures, code comments. Breaking these links during migration produces real productivity loss. The mitigation: implement URL redirects from old Confluence URLs to new portal URLs, either through an internal redirect service or by keeping Confluence in archive mode with explicit redirects configured for the high-value pages. Typical cost: $5,000 to $15,000 of platform-team time.

The Historic-Page Abandonment Decision

Most Confluence estates contain large amounts of historic content. Decade-old design documents from projects that shipped or were cancelled, defunct service pages for services that were deprecated long ago, runbook drafts that never went live, meeting notes from architecture review boards that no longer exist. Migrating all of this to a new portal is expensive (the migration cost scales roughly linearly with page count for non-automatable portions) and produces little value because most of the historic content has not been accessed in years.

The decision: migrate selectively or migrate comprehensively. Selective migration is the right answer for most organisations. The high-value content (current service documentation, active runbooks, current on-call procedures) moves to the portal where it can benefit from the docs-as-code discipline. The low-value historic content stays in Confluence in archive mode (or gets archived to cold storage with the Confluence space marked read-only). Engineers needing historic content can still find it in Confluence; engineers needing current content find it on the portal where it is genuinely current.

The selective approach typically migrates 20 to 40 percent of Confluence pages and reduces the migration cost by 50 to 70 percent compared to a comprehensive migration. The value loss from leaving 60 to 80 percent of pages behind is small because the unmigrated pages were not being used anyway. A comprehensive migration is rarely justified by usage data; the temptation is to want a clean break from Confluence, which is real but rarely worth the cost.

Ownership Migration Specifics

Confluence's page-level permission model does not translate cleanly to a developer portal's repository-level or entity-level permission model. Pages restricted to a specific Confluence space group (often for sensitive content like security incident retrospectives, vendor contracts, board-level reporting) have to be re-permissioned in the portal's access control model. The work covers identifying the restricted pages (typically automatable from the Confluence API), determining the portal-side equivalent permission, applying the new permission, and verifying the access control is correct. For most organisations the restricted content set is small (under 5 percent of service documentation) but the work is fiddly because each case requires individual judgement. Typical cost: $20,000 to $40,000 of platform-team time depending on the restricted content volume. For broader context on the ongoing documentation cost picture after migration, see the TechDocs cost page; for the broader build-or-buy framing the migration sits inside, see the build vs buy page.

Frequently Asked Questions

How much does Confluence-to-portal migration cost?

Typical year-one migration cost is $80,000 to $200,000 of platform-engineer time over 3 to 6 months elapsed. The cost is spread across catalogue bootstrap from existing Confluence service pages ($20,000 to $50,000), TechDocs migration of high-value service documentation ($20,000 to $80,000), redirect strategy implementation ($5,000 to $15,000), and ownership migration ($20,000 to $40,000). Wide variance because some organisations have well-structured Confluence service estates that migrate cleanly while others have decade-old Confluence content with significant historic-page abandonment to handle.

What is the historic-page abandonment decision?

Most Confluence estates contain large amounts of historic content (decade-old design documents, defunct project pages, runbook drafts that never went live, meeting notes). Migrating all of this to a new portal is expensive and produces little value because most of it has not been accessed in years. The decision: migrate selectively (high-value service documentation moves to the portal, low-value historic content stays in Confluence in archive mode or gets archived to cold storage) or comprehensively (migrate everything). Selective migration is the right answer for most organisations because the cost savings are large and the value loss is small.

What does the redirect strategy involve?

Confluence service-documentation URLs are typically referenced across the engineering organisation in Slack messages, runbooks, on-call escalation procedures, internal documentation, code comments. Breaking these links during migration produces real productivity loss as engineers find dead links and lose access to important context. The standard mitigation: implement URL redirects from old Confluence URLs to new portal URLs (typically through an internal redirect service or by keeping Confluence in archive mode with redirects configured), document the migration in internal communications channels, and run a discovery phase to identify high-value Confluence URLs that need explicit redirect entries. Total redirect implementation cost: $5,000 to $15,000 of platform-engineer time.

What about Confluence page-level permissions?

Confluence's page-level permission model does not translate cleanly to a developer portal's repository-level or entity-level permission model. Pages restricted to a specific Confluence space group have to be re-permissioned in the portal's access control model. The work is mostly identifying the restricted pages (often automatable from the Confluence API), determining the portal-side equivalent permission (sometimes a portal team, sometimes a specific RBAC role), and applying the new permission. For most organisations the restricted content set is small (typically under 5 percent of service documentation) but the work is fiddly and time-consuming because each case requires individual judgement.

What about Confluence content that does not exist as pages but as databases or macros?

Confluence has its own database tables, table macros, and various plugin-extended content types that do not have clean markdown equivalents. The standard mitigation: leave database-style content in Confluence (the portal does not try to replace it), or rebuild the most important data as native portal entities. The decision depends on usage volume; a Confluence table that the engineering team consults weekly probably justifies the rebuild work, a Confluence table that nobody looks at after the original author left probably does not.

What is the realistic year-three TCO including the migration?

Year-one $80,000 to $200,000 migration plus $20,000 to $50,000 of TechDocs and portal ongoing maintenance. Years two and three at $30,000 to $80,000 per year of platform-engineer time on documentation freshness and portal maintenance. Three-year cumulative: $150,000 to $400,000. The TCO includes the deferred ongoing cost of documentation maintenance which existed before the migration too; the migration itself does not create ongoing cost, it transfers ongoing cost from Confluence to portal-side.