Skip to main content
Add Confluence as a context provider to give your agent access to the documentation, wikis, and runbooks your team keeps in Confluence. Works with both Confluence Cloud and Confluence Data Center/Server.

​
Why add Confluence?

Syncing Confluence lets your agent:
  • Answer questions using your team’s internal documentation
  • Reference business definitions, metric glossaries, and data dictionaries
  • Use onboarding docs, runbooks, and process guides as context

​
Adding Confluence

During initialization When you run nao init, the wizard prompts for Confluence interactively:
It asks for your base URL, the deployment flavour, credentials, and what to sync. Manual configuration Add a confluence block to your nao_config.yaml:
Confluence needs the optional confluence extra:
Never commit Confluence credentials to Git. Use {{ env('VAR') }} for every secret.

​
Connection

​
Authentication

Credentials differ by deployment.
Cloud uses Basic auth with an Atlassian API token. Both fields are required:

​
Choosing what to sync

Four selectors decide which pages are pulled. They combine, and a page selected twice is only synced once. At least one of them must be set - a confluence block with none of them fails validation.
Only pages and blog posts are synced. Whiteboards, databases, and attachments expose no text through the API and are skipped.

​
What happens at nao sync

When you run nao sync, nao:
  1. Resolves every selector into a single set of pages
  2. Fetches each page’s body and converts the rendered HTML to markdown
  3. Writes the markdown under docs/confluence/ in your nao project
Each file carries YAML frontmatter with the page’s title, id, space, version, and url, so the agent can cite the source page.

​
Folder layout

Files mirror the Confluence page tree. Pages live under their space, then under a directory per ancestor. A page that has synced children keeps its own body in a file beside the directory holding them. Blog posts have no tree, so they collect under blog/ in their space.

​
Incremental syncs

nao records each page’s Confluence version in its frontmatter. On the next run, a page whose version is unchanged is left alone instead of being re-fetched, so repeat syncs only pay for what actually changed. Pages that disappear from your selectors are cleaned up - but only after a run that succeeded in full. If any page failed to fetch or write, stale files are kept in place rather than risk deleting content over a transient error.

​
Images

Confluence images point at attachment URLs that need the same auth as the API, so a bare reference is of no use to the agent. Every image is replaced with an [image] placeholder in the exported markdown.

​
Editing synced files

Files under docs/confluence/ are read-only in the File Explorer, the same as docs/notion/ and repos/. They are replaced on every nao sync, so edits belong in Confluence itself, or in the confluence block of nao_config.yaml. Next Steps

Context Configuration

Initialize and configure your nao project

Synchronization

Learn how to sync and update your agent’s context