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:
- An Atlassian Cloud site with Confluence enabled. Data Center and Server are not supported.
- Admin access to the Confluence site so you can approve the OAuth scopes during the connection flow.
- 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
confluencefeature flag. - A destination folder in the workspace file system for each Confluence space you plan to sync. You can create folders under File Browser before or after starting the connection — whichever is easier.
Connecting Confluence
- Go to App Connections and open the Directory tab.
- Find Confluence (under Knowledge Base) and click Add.
- Open Setup and click Connect Confluence — you'll be redirected to
auth.atlassian.comto sign in. - Choose the Atlassian site whose Confluence spaces you want to sync.
- Approve the requested scopes. Gravity Rail requests read-only access to spaces and page content plus
offline_accessso the sync can keep running without re-prompting. - 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, disconnect the existing connection first (from the Active tab, as below).
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 Settings tab to configure which Confluence spaces sync into which workspace folders.
- Click Add Space.
- In the Confluence Space dropdown, pick one of the spaces the connected account can see.
- In the Destination Folder selector, pick the workspace folder where pages should land. Start typing to filter the folder list.
- 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.
- 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 Settings 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 Sync 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 Sync 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
Reconnect Required
The Atlassian access token has expired or been revoked. Use Reconnect in the connection header to authorize again. For a connected account, the action is in the header's three-dot menu. If the authorizing user no longer has access, disconnect and authorize with an account that can read the required spaces.
A space I expect doesn't appear in the dropdown
The OAuth grant is scoped to whichever Atlassian site you picked when connecting. Spaces on a different site are not visible. If the account you authorized cannot read the space, ask a Confluence admin for access, then use Reconnect in the connection header.
Pages are missing or out of date
- Check that the space is mapped in the Settings 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 Sync 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
Open the connection header's three-dot menu, choose Disconnect, and confirm. This signs the connection out and stops syncing. Your configuration stays; open Setup to authorize again. Setup also shows who authorized the connection, the OAuth callback URL, and scopes. Sync keeps your past runs available read-only after disconnecting; Settings stays hidden until you reconnect.
To remove the Confluence integration entirely:
- Go to the Active tab on the App Connections page.
- Open the row's action menu and choose Disconnect. Unlike the connection header's Disconnect, this deletes the connection and its sync settings.
Files already synced into workspace folders remain in place after you disconnect the connection. 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
- File Browser and File Editor — Managing the workspace file system where synced pages live
- HubSpot Sync — Companion guide for member sync (different concepts, similar flow)