Confluence to Google Workspace Migration: The Technical Guide

There is no native migration path from Confluence to Google Workspace. Google Workspace Migrate does not list Confluence as a supported source (support.google.com). Confluence stores content as XHTML with custom XML elements for macros, layouts, and structured data inside a hierarchical Space → Page → Child Page tree. Google Workspace distributes content across Shared Drives (folders and files), Google Docs (flat documents), and optionally Google Sites (flat page collections). Every viable migration approach requires you to extract Confluence content via export or API, transform the markup, flatten or re-map the hierarchy, and load it into Google's APIs — all while handling macro loss, broken internal links, and permission mismatches.

This guide covers the architecture clash, every migration method with its real constraints, the API rate limits on both sides, data mapping decisions, and the edge cases that silently corrupt migrations. If you need to get your data out of Confluence first, start with How to Export All Data from Confluence: Methods, Limits & Tools. If you're evaluating SharePoint instead of Google as a target, see Confluence to SharePoint Migration: Methods, Limits & Macro Mapping.

Architecture Clash: Confluence Spaces vs. Google Drive Folders

Understanding the data model mismatch is the first step. Skip it and you'll build a migration that technically runs but produces an unusable knowledge base.

Confluence organizes content in Spaces, each containing a tree of Pages with unlimited nesting depth. Pages hold rich text in Confluence Storage Format (XHTML with custom XML elements for macros like <ac:structured-macro>) or Atlassian Document Format (ADF, a structured JSON model) in Cloud. Inline images and file attachments are stored per-page. Permissions are set at Space, Page, and restriction levels. Everything is interconnected through internal wiki links using page titles or page IDs. (developer.atlassian.com)

Google Workspace has no equivalent wiki structure. Content lives in Shared Drives (team-owned containers) or My Drive (individually owned). Documents are Google Docs — flat, linear documents without parent-child relationships. Structure comes from folders, not page trees. The Docs API gives you text, tables, images, person mentions, and rich links — not a macro engine. (support.google.com)

The constraints are specific and non-negotiable:

• Shared Drives are capped at 500,000 items (files, folders, shortcuts, and trash combined). This is a hard limit based on item count, not storage. Folders also cap at 500,000 direct items. (support.google.com)
• Folder nesting is limited to 100 levels in Shared Drives. Attempts to exceed this return a teamDriveHierarchyTooDeep error.
• Upload bandwidth is capped at 750 GB per day per user account across all drives.
• Google Docs have a ~1.02 million character limit, and converted text documents can be up to 50 MB. (support.google.com)
• Google Docs have no native macro system. Confluence macros like Jira issue links, draw.io diagrams, dynamic tables, and Table of Contents have no Google Docs equivalent.

Data Model Mapping

If you map a Confluence Space to a Google Shared Drive, every parent page becomes a folder, and the content of that parent page becomes a Google Doc inside that folder. Child pages become nested Google Docs in subfolders. This creates a structural mismatch that requires programmatic resolution.

Migration Approaches: Native Export, APIs, and Custom ETL

There are four viable approaches. Each has clear trade-offs in fidelity, scalability, and engineering effort.

Method 1: Native HTML/XML Export → Manual Upload to Drive

How it works: Export a Confluence Space as HTML or XML via Space Settings → Export Space. Upload the resulting ZIP contents into Google Drive. Optionally convert HTML files to Google Docs using Drive's built-in conversion.

When to use it: Small spaces (under 100 pages) with simple text content, no macros, and no requirement to preserve internal links.

Limitations are significant. Confluence's native HTML export places page attachments in isolated folders named by page ID (download/attachments/<pageId>), not by page title. Reconstructing which attachment belongs where requires parsing the HTML and cross-referencing IDs. The HTML export also does not include blog posts — a documented, long-standing limitation. XML exports include blog posts and comments but use Atlassian's proprietary schema that Google Workspace cannot parse. Word exports are limited to the first 50 images per page to prevent out-of-memory errors, and the exported .doc file is explicitly incompatible with Google Docs. (support.atlassian.com)

Method 2: Confluence REST API → Google Drive & Docs APIs

How it works: Write a script that walks the Confluence page tree via the REST API, extracts each page's body in storage format (XHTML) or atlas_doc_format (ADF JSON), transforms the content into Google Docs format, and creates corresponding Docs and folders via the Google Drive/Docs APIs.

The Confluence v2 REST API endpoint GET /wiki/api/v2/pages returns page metadata including parentId, letting you reconstruct the tree. To get page content, request with body-format=storage to receive the raw Confluence Storage Format. If you need rendered HTML for macro fallback rather than raw storage XML, Confluence also exposes asynchronous content-body conversion endpoints. (developer.atlassian.com)

When to use it: Mid-size migrations (100–5,000 pages) where you need programmatic control over hierarchy mapping, link rewriting, and attachment handling.

Rate limits on both sides will throttle you. Confluence Cloud enforces a points-based rate limiting model as of March 2, 2026. Each API call consumes points based on complexity, not just request count. The default Global Pool quota is 65,000 points per hour, shared across all tenants using your app. Quotas reset at the top of each UTC hour with no carry-over — once exhausted, all requests are blocked until the next hour. (developer.atlassian.com)

On the Google side, the Drive API uses quota units measured per minute per project. The sustained write rate limit is 3 requests per second per account, and this limit cannot be increased. Exceeding it returns 403 or 429 errors. For large migrations, Google recommends using service accounts with domain-wide delegation to spread the load across multiple user contexts.

Method 3: Third-Party Migration Tools

How it works: Tools like CloudM, AvePoint, or Marketplace connectors offer UI-based workflows that read from Confluence and write to Google Drive. You authenticate both systems via OAuth, and the tool attempts to map pages to Docs.

When to use it: When you want a faster path than custom scripting and your content is mostly flat text pages without heavy macro usage.

The gap is consistent across vendors: third-party tools typically sync flat content but fail to preserve deeply nested page tree hierarchies or convert complex Atlassian Document Format elements. Jira macros, draw.io diagrams, and dynamic tables are either dropped or rendered as broken placeholder text. Internal wiki links between pages are almost never rewritten to point to the new Google Docs URLs. Google's own migration stack does not list Confluence as a source. (support.google.com)

Method 4: Custom ETL Pipeline

How it works: Build a full Extract-Transform-Load pipeline: extract all content and metadata via the Confluence API into staging storage, transform it through custom parsers (HTML cleanup, macro replacement, link rewriting, user mapping), and load into Google Workspace via Drive and Docs APIs with full error handling, retry logic, and validation. For delta waves, pair the source-to-target manifest with CQL queries on changed content instead of recrawling every page. (developer.atlassian.com)

When to use it: Enterprise migrations (5,000+ pages), complex permission structures, deep page hierarchies, heavy macro usage, or when you need delta migration capability (migrating only what changed since the last run).

This is the approach that managed migration services — including ClonePartner — use internally. The investment is in the transformation layer: parsing Confluence Storage Format, converting each element to Google Docs API requests, handling edge cases like inline attachments, and building an internal link rewriting map.

Approach Comparison

Recommendations by Scenario

• Small business (< 500 pages, light macros): A curated API migration works. Native export is acceptable for archives but not for a production knowledge base.
• Enterprise (1,000+ pages, multiple Spaces, complex macros): Use API-driven migration, custom ETL, or a managed service. Rehearse ACL mapping and link rewriting before cutover.
• Point-in-time delta before cutover: Rerun changed pages and attachments near go-live using CQL queries or lastModified timestamps. Do not build a permanent sync bridge unless the business case is unusually strong.
• Low engineering bandwidth: Do not build in-house if nobody can own the manifest, retries, validation, UAT, and cleanup for several weeks after go-live.

The Macro Problem: What Breaks in Google Docs

This is where most migrations lose fidelity. Confluence's power comes from its macro ecosystem, and Google Docs has no equivalent runtime. (confluence.atlassian.com)

Macros that have no Google Docs equivalent:

• Jira Issue Macro — Renders live Jira ticket data. Best conversion: extract the ticket key and summary, rewrite as a static hyperlink to the Jira URL, or use a Google Docs Smart Chip if the URL resolves.
• draw.io / Gliffy Diagrams — Embedded interactive diagrams. Confluence stores these as attached .xml and .png files. Export as PNG/SVG and insert as static images. Editability is lost.
• Table of Contents Macro — Auto-generated TOC from headings. Google Docs has a built-in TOC feature, but it must be inserted separately — it won't auto-generate during API import.
• Page Properties / Page Properties Report — Structured metadata extraction across pages. No equivalent in Google Docs. Convert to a static table or move the workflow to a linked Google Sheet.
• Expand/Collapse Macro — Toggleable content sections. Google Docs has no collapsible sections. Content must be flattened into standard headings and paragraphs.
• Code Block Macro — Syntax-highlighted code. Google Docs has no native code formatting. Use monospace font or link to a separate code file.
• Include Page / Excerpt Include — Content pulled dynamically from other pages. Must be resolved to static content at migration time; the live relationship is permanently severed.

For more on macro conversion patterns, see Confluence to SharePoint Migration: Methods, Limits & Macro Mapping.

Pre-Migration Planning & Data Audit

Before writing a single line of migration code, inventory what you have and decide what you're actually moving.

Data Audit Checklist

• Total Spaces — Count and categorize (active vs. archived)
• Total Pages and Blog Posts — Per space, including draft vs. published. Run CQL queries to find pages not updated in 12+ months; consider archiving instead of migrating.
• Attachment Volume — Total size and count; identify any files > 100 MB (Confluence stops indexing content beyond this)
• Macro Usage — Query the API to list all unique macros used across the instance. Flag Jira macros, draw.io, code blocks, include-page macros, and other dynamic content. Decide how each will be transformed.
• Internal Links — Count cross-space and intra-space wiki links
• Comments — Inline comments vs. page-level comments
• Permissions — Space-level permissions, page-level restrictions, group memberships. Map Atlassian group access to Google Workspace groups.
• User List — Map Atlassian account IDs (UUIDs) to Google Workspace email addresses
• Unpublished Drafts — Native exports exclude drafts; API extraction is required to capture them
• Stale Content — Pages not modified in 12+ months. Decide whether to archive or migrate.

Back up Confluence before you start. Full site backup via Administration → Backup Manager. Keep it for 90 days minimum. (support.atlassian.com)

Migration Strategy: Big Bang vs. Phased

Big bang — Migrate everything in one pass over a weekend. Works when total volume is under 10,000 pages and you can freeze Confluence writes during migration. Risk: if validation fails, rollback scope is large.

Phased — Migrate Space by Space, starting with the least complex. Validate each Space before proceeding. Preferred for enterprise instances with 50+ Spaces. Allows you to refine the transformation pipeline iteratively.

Delta migration — After an initial bulk migration, re-run the pipeline to capture only pages modified since the last run. This is critical when the migration spans days or weeks and content is still being authored in Confluence. Building delta detection requires tracking page version numbers or lastModified timestamps.

Step-by-Step API Extraction and Transformation

Here is the technical workflow for an API-based migration. This applies whether you build it yourself or outsource to a managed service.

Step 1: Extract from Confluence

Use the Confluence REST API v2 to walk the page tree. For each page, the response includes parentId and spaceId, allowing you to reconstruct the full hierarchy. Extract body.storage.value for the raw XHTML content.

import requests
from requests.auth import HTTPBasicAuth
import time
 
BASE_URL = "https://your-domain.atlassian.net/wiki/api/v2"
AUTH = HTTPBasicAuth("email@company.com", "API_TOKEN")
HEADERS = {"Accept": "application/json"}
 
def get_pages_in_space(space_id, cursor=None):
    params = {"space-id": space_id, "body-format": "storage", "limit": 25}
    if cursor:
        params["cursor"] = cursor
    resp = requests.get(f"{BASE_URL}/pages", params=params, auth=AUTH,
                        headers=HEADERS)
 
    if resp.status_code == 429:  # Handle Atlassian rate limiting
        retry_after = int(resp.headers.get("Retry-After", 5))
        time.sleep(retry_after)
        return get_pages_in_space(space_id, cursor)  # Retry
 
    resp.raise_for_status()
    return resp.json()
 
def get_attachments(page_id, cursor=None):
    params = {"limit": 25}
    if cursor:
        params["cursor"] = cursor
    resp = requests.get(f"{BASE_URL}/pages/{page_id}/attachments",
                        params=params, auth=AUTH, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()

Step 2: Transform Content

This is the hardest step. You need to:

1. Parse Confluence Storage Format XHTML — Use an HTML parser (e.g., BeautifulSoup, Cheerio) to walk the DOM.
2. Convert HTML elements to Google Docs API requests — The Google Docs API uses batchUpdate with structured request objects (InsertText, InsertInlineImage, UpdateTextStyle, etc.), not HTML. You cannot send raw HTML to the Docs API; every element must become a JSON command.
3. Replace macros with static equivalents — Detect <ac:structured-macro> elements, extract parameters, and generate the appropriate static replacement (text, image, hyperlink, or Smart Chip).
4. Queue internal links for second-pass rewriting — Build a lookup map of {confluence_page_id: google_doc_id} and rewrite all <a> tags pointing to Confluence URLs after all Docs are created.
5. Handle inline attachments — Images referenced as <ac:image> with <ri:attachment> must be downloaded from Confluence and uploaded to Drive, then linked in the new Doc at the correct insertion point.
6. Map users — Replace Atlassian account IDs in @mentions and comments with Google Workspace email addresses.

Step 3: Load into Google Workspace

Create the folder structure in Shared Drives first, then create Google Docs for each page and insert transformed content via batchUpdate API calls.

from google.oauth2 import service_account
from googleapiclient.discovery import build
 
SCOPES = ['https://www.googleapis.com/auth/drive',
          'https://www.googleapis.com/auth/documents']
creds = service_account.Credentials.from_service_account_file(
    'service-account.json', scopes=SCOPES)
 
drive_service = build('drive', 'v3', credentials=creds)
docs_service = build('docs', 'v1', credentials=creds)
 
def create_folder(name, parent_id, drive_id):
    metadata = {
        'name': name,
        'mimeType': 'application/vnd.google-apps.folder',
        'parents': [parent_id],
        'driveId': drive_id
    }
    return drive_service.files().create(
        body=metadata, supportsAllDrives=True, fields='id'
    ).execute()
 
def create_doc(title, parent_folder_id):
    doc = docs_service.documents().create(body={'title': title}).execute()
    # Move doc to target folder
    drive_service.files().update(
        fileId=doc['documentId'],
        addParents=parent_folder_id,
        removeParents='root',
        supportsAllDrives=True
    ).execute()
    return doc['documentId']

The sustained write rate limit on Drive API is 3 requests per second per account. For a migration of 5,000 pages with 3 attachments each, that's roughly 20,000 write operations — over 100 minutes at max sustained throughput, not counting retries. Use service accounts with domain-wide delegation to spread the load. (developers.google.com)

Step 4: Rebuild Internal Links

Confluence internal links use constructs like <ac:link><ri:page ri:content-title="Target Page"/></ac:link>. Because Google Doc IDs are generated only after the document is created, you must do a second pass over all imported Google Docs to rewrite links using the stored ID mapping table:

def rewrite_links_in_doc(doc_id, link_map):
    """Replace Confluence URLs with Google Doc URLs in a document."""
    doc = docs_service.documents().get(documentId=doc_id).execute()
    requests_batch = []
    # Walk document body, find links, build UpdateTextStyle requests
    # targeting the old URL and replacing with the new Google Doc URL
    # ... (implementation depends on document structure parsing)
    if requests_batch:
        docs_service.documents().batchUpdate(
            documentId=doc_id, body={'requests': requests_batch}
        ).execute()

Error Handling and Logging

Build these into every step:

• Retry with exponential backoff — On 429 responses from either API, respect the Retry-After header. Start with a 1-second delay, double on each retry, cap at 5 retries.
• Idempotency tracking — Log every Confluence page ID → Google Doc ID mapping to a database or file. If the script crashes, resume from the last successful page.
• Content hash validation — Hash the source content before transformation and the target content after load. Compare to detect silent corruption.
• Per-page error log — Log failures with the Confluence page ID, error type, and response body. Don't let one bad page halt the entire migration. Quarantine pages with unsupported constructs instead of silently flattening them.

Edge Cases That Derail Migrations

These are the issues that don't appear in test migrations of 10 pages but surface at scale:

• Deeply nested hierarchies — Confluence allows unlimited page nesting. Google Shared Drives cap at 100 folder levels. If your Confluence tree exceeds this, you need to flatten intermediate levels — which breaks the organizational logic users expect. Design your flattening strategy before you start loading.
• Inline attachments vs. block attachments — Confluence distinguishes between images embedded in page body (<ac:image>) and files attached to the page but not embedded. Inline images must be inserted at the correct document position via the Docs API; block attachments go to the parent folder in Drive. Both need different handling.
• Cross-space links — Pages linking to content in other Spaces require the target Space to be migrated first, or links must be queued for a second-pass rewrite after all Spaces are loaded.
• User identity mapping — Confluence uses Atlassian Account IDs (UUIDs). Google uses email addresses. If users don't have matching emails, permissions and comment attribution break silently. Resolve the mapping before you start loading. (support.atlassian.com)
• API throttling under load — Confluence's points-based quota resets at the top of each UTC hour. A migration that starts at 12:50 UTC may exhaust its quota in 10 minutes and sit idle for 50. On Google's side, exceeding the per-second write limit triggers 403/429 errors that require backoff.
• Large attachments — Confluence allows large file attachments but stops indexing content beyond 100 MB. Google Drive allows files up to 5 TB, but the 750 GB/day upload cap means a space with 800 GB of attachments takes two calendar days minimum.
• Permission inheritance on move — Avoid staging content in My Drive and moving it into Shared Drives later. Google notes that inherited folder permissions are not copied when a child folder is moved into a Shared Drive. Create content directly in the target Shared Drive. (developers.google.com)
• Comments and mentions — Drive comments can be recreated, including anchored comments, but exact positions can drift after content conversion. Preserve author and timestamp in the comment body if exact anchors can't be recreated. (developers.google.com)

Limitations You Cannot Engineer Around

Be honest with stakeholders about what changes permanently after migration:

• Wiki structure is gone. Google Docs are flat documents in folders. The parent-child page relationship that makes wiki navigation intuitive doesn't exist in Drive. Users navigate by search, not by tree.
• Dynamic macros become static. Any Confluence macro that queries live data (Jira, databases, other pages) becomes frozen text. This is permanent functionality loss, not a temporary gap.
• Permission granularity differs. Confluence supports page-level restrictions independent of Space permissions. Google Drive inherits permissions from parent folders by default — restricting access at the individual Doc level requires explicitly setting "limited access" on folders. Exact Confluence parity is not always possible. (support.atlassian.com)
• Formatting fidelity is imperfect. Confluence Storage Format supports complex layouts (multi-column sections, panel macros, status macros) that have no Google Docs equivalent. Expect visual differences.

Validation and Testing

Don't declare a migration complete until you've validated these dimensions:

1. Document count comparison — Total pages in Confluence vs. total Docs in Google Drive. Account for intentionally excluded content (archived spaces, stale pages).
2. Attachment count and size — Compare total attachment count and aggregate file size between source and target.
3. Internal link integrity — Sample 10% of Docs and verify that internal links resolve to the correct target Doc, not a dead URL or an atlassian.net address.
4. Formatting spot-check — Visually compare 5–10 complex pages (those with tables, images, code blocks, multi-column layouts) against their Confluence originals.
5. Permission audit — For each migrated Space, verify that the Shared Drive members match the original Confluence Space permissions.
6. User Acceptance Testing (UAT) — Have content owners from each team verify their migrated Spaces. They'll catch organizational issues that automated checks miss.

Rollback plan: Keep Confluence in read-only mode for 2–4 weeks post-migration. If critical issues surface, users can fall back. Do not delete the Confluence instance until UAT is formally signed off.

Post-Migration Tasks

• Rebuild document workflows — Confluence page approvals, watch notifications, and automation rules don't carry over. Recreate them using Google Workspace tools (Drive activity notifications, Apps Script automations).
• User training — Teams accustomed to wiki navigation need guidance on Drive search, Shared Drive organization, and Google Docs collaboration patterns. The shift from wiki navigation to folder navigation is significant. Give teams time to adjust.
• Monitor access issues — Permission mapping errors often surface days after migration when someone who should have access tries to open a Doc. Set up a dedicated support channel for the first two weeks.
• Archive or delete Confluence — Once UAT is complete and the read-only fallback period has passed, export a final Confluence backup and decommission the instance.

When to Use a Managed Migration Service

Build in-house when:

• Your instance has fewer than 500 simple text pages with no macros
• You have a dedicated engineer with 4+ weeks of availability
• You don't need permission mapping or internal link rewriting

Use a managed service when:

• Your instance has 1,000+ pages, multiple Spaces, or complex macro usage
• You need delta migration (migrating changes since the initial bulk run)
• You can't afford to dedicate engineering time to a one-time infrastructure project
• Permission mapping, user mapping, or compliance requirements add risk
• You've already attempted a DIY migration and hit issues at scale

The hidden cost of DIY migration isn't the initial script — it's the edge cases. Handling Confluence's macro taxonomy, building the internal link rewriting map, implementing retry logic for two different rate-limiting systems, and validating thousands of pages takes engineering time that could ship product features instead. For a deeper analysis of this trade-off, see The Data Migration Risk Model: Why DIY AI Scripts Fail and How to Engineer Accountability. If you're evaluating providers, see How to Choose an Enterprise Knowledge Base Migration Service.

What ClonePartner Brings to This Migration

We've built extraction and transformation pipelines for Confluence migrations across hundreds of engagements. Here's what that means in practice:

• Point-in-time delta migrations — We run an initial bulk migration, then re-run on your schedule to capture only pages changed since the last pass. We don't build continuous sync bridges — we deliver clean, validated snapshots.
• Macro conversion — Our pipeline handles the full Confluence macro taxonomy, converting each to the closest Google Docs equivalent (static text, images, Smart Chips, or linked Sheets) with a documented conversion report.
• Nested hierarchy handling — We programmatically map your page tree to Google Drive's folder structure, flattening where necessary and preserving navigability.
• Permission and ACL mapping — We map Confluence Space permissions and page-level restrictions to Google Shared Drive roles and limited-access folders.
• Zero downtime — Your Confluence instance stays live throughout. We extract via API without affecting your team's daily work.

This is the kind of migration we do every week. If you want to skip the 4–12 weeks of pipeline engineering and get to validated results in days, we can scope it in a single call.

Best Practices Checklist

• Back up Confluence before migration — Full site backup via Administration → Backup Manager. Keep it for 90 days minimum.
• Run test migrations on your most complex Space first — This reveals macro conversion issues, formatting edge cases, and rate limit behavior early. Don't start with the easy spaces.
• Automate internal link rewriting — Never attempt this manually. Build the page ID → Doc ID map programmatically and batch-update all links.
• Use service accounts for Google API writes — Spread load across multiple user contexts to avoid per-user rate limits. Google officially recommends this for large migrations.
• Don't preserve deep trees blindly — Evaluate whether your Confluence hierarchy still makes sense in a folder-based system. A migration is an opportunity to restructure.
• Validate incrementally during delta phases — Don't wait until the final migration to check fidelity. Validate after each pass.
• Pick your target model before your tool — If your future state is living docs, target Shared Drives and Google Docs. If you need a browsable portal, keep Docs as the source of truth and use new Google Sites as a thin navigation layer. What usually fails is trying to preserve every Confluence behavior exactly.
• Communicate the change to users early — Give teams time to adjust their mental model from wiki navigation to folder navigation.