Confluence Sync

Connect Atlassian Confluence Cloud to your workspace and sync selected spaces into folders as Markdown files. Once configured, every page in the mapped spaces appears in the workspace virtual file system — where agents retrieve it for RAG and where members can search or browse it like any other folder.

Confluence sync is currently inbound only (Confluence to Gravity Rail) and read-only: pages are pulled on a schedule or on demand, but Gravity Rail never writes back to Confluence.

Before You Start

You'll need:

1. An Atlassian Cloud site with Confluence enabled. Data Center and Server are not supported.
2. Admin access to the Confluence site so you can approve the OAuth scopes during the connection flow.
3. The Confluence feature enabled on your workspace. If you don't see Confluence in the App Connections directory, ask your Gravity Rail administrator to turn on the confluence feature flag.
4. A destination folder in the workspace file system for each Confluence space you plan to sync. You can create folders under Files before or after starting the connection — whichever is easier.

Connecting Confluence

1. Go to App Connections and open the Directory tab.
2. Find Confluence (Knowledge category) and click Install.
3. Click Connect — you'll be redirected to auth.atlassian.com to sign in.
4. Choose the Atlassian site whose Confluence spaces you want to sync.
5. Approve the requested scopes. Gravity Rail requests read-only access to spaces and page content plus offline_access so the sync can keep running without re-prompting.
6. You'll be redirected back to your workspace. The new connection appears on the Active tab.

Only one Confluence connection is supported per workspace (singleton). If you need to switch sites, delete the existing connection first.

Use a service account where possible. OAuth grants are tied to the user who authorized them. If that user leaves your organization or revokes the integration's access, sync stops working. For production knowledge-base sync, authorize with a dedicated Atlassian service account.

Mapping Spaces to Folders

After connecting, open the Confluence connection's Sync tab to configure which Confluence spaces sync into which workspace folders.

1. Click Add Space.
2. In the Confluence Space dropdown, pick one of the spaces the connected account can see.
3. In the Destination Folder selector, pick the workspace folder where pages should land. Start typing to filter the folder list.
4. Add more mappings if you need multiple spaces. Each space can only map to one destination folder, and a space can't be mapped twice.
5. Click Save Sync Settings.

The mappings you save are stored on the connection and used for every subsequent sync — manual or scheduled.

How Pages Land in the Destination Folder

• Each Confluence space becomes a top-level subfolder under its destination folder.
• Each parent page in Confluence becomes a nested subfolder.
• Each page is created as a Markdown file inside that folder hierarchy. The file's title matches the Confluence page title.
• Page content is converted from Confluence's XHTML "storage format" to Markdown so agents and members can read it as plain text.
• The source Confluence page URL is preserved on the file so agents can cite it.

Removing a Mapping

To stop syncing a space, click the trash icon next to its row in the Sync tab and click Save Sync Settings. Files previously created by that mapping remain in the destination folder unless you delete them manually.

Running a Sync

Manual Sync

From the connection's Logs tab, click Sync Now to run a full sync immediately. Progress streams live to your browser — you'll see each page as it's fetched and converted.

Scheduled Sync

Once sync is configured, Gravity Rail runs a background sync on a regular cadence and only fetches pages that have changed since the last successful run (incremental sync using Confluence's CQL lastModified filter). You don't need to schedule anything by hand.

Viewing Sync Logs

The Logs tab shows recent sync runs: when they started, how many pages were processed, and any errors. Click a run to expand it and see per-page detail. Failed pages appear highlighted with the provider's error message attached.

Troubleshooting

"Reauthorize Required" badge

The Atlassian access token has expired or been revoked. Open the connection and click Reauthorize to re-run the OAuth flow. If the authorizing user no longer has access, delete the connection and reconnect with a service account.

A space I expect doesn't appear in the dropdown

The OAuth grant is scoped to whichever Atlassian site you picked during Connect. Spaces on a different site are not visible. If the account you authorized doesn't have access to the space, ask a Confluence admin to grant access and then click Reauthorize.

Pages are missing or out of date

• Check that the space is mapped in the Sync tab and that you saved after adding the mapping.
• Run Sync Now once to confirm the space fetches correctly — scheduled syncs pick up changes on an interval.
• Check the Logs tab for the most recent run. Per-page errors (rate limit, permission denied, content too large) are shown there.

Sync completes but content looks wrong

The content converter turns Confluence's XHTML storage format into Markdown. Complex macros and embedded attachments may render as plain text or be skipped. File a bug with an example page link if a specific construct isn't converting cleanly.

Rate-limit or timeout errors

Confluence throttles API requests per site. Large initial syncs may retry automatically. If retries don't resolve it, stagger mappings (save one space, let it sync, then add the next).

Disconnecting

To remove the Confluence integration:

1. Go to the Active tab on the App Connections page.
2. Open the connection's action menu and choose Disable (pause sync, keep config) or Delete (remove entirely).

Files already synced into workspace folders remain in place after disable or delete. Remove them manually if you want them gone.

Also revoke from Atlassian. Deleting the connection in Gravity Rail removes our copy of the OAuth token, but Atlassian keeps its own record of the grant. To fully revoke access, sign in to id.atlassian.com and remove Gravity Rail from Connected Apps.

Related

• App Connections — Overview of the integration hub
• Files — Managing the workspace file system where synced pages live
• HubSpot Sync — Companion guide for member sync (different concepts, similar flow)