> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getnao.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Confluence
> Sync Confluence pages, spaces, and labels into your agent context
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:
```bash theme={null}
nao init
```
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`:
```yaml theme={null}
confluence:
base_url: https://acme.atlassian.net/wiki
deployment: cloud
email: {{ env('CONFLUENCE_EMAIL') }}
api_token: {{ env('CONFLUENCE_API_TOKEN') }}
spaces:
- DATA
```
Confluence needs the optional `confluence` extra:
```bash theme={null}
pip install 'nao-core[confluence]'
```
Never commit Confluence credentials to Git. Use `{{ env('VAR') }}` for every secret.
### Connection
| Field | Description |
| ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `base_url` | Absolute HTTP(S) URL. `https://acme.atlassian.net/wiki` on Cloud, `https://confluence.acme.com` on Data Center/Server. |
| `deployment` | `cloud` (default) or `server`. |
### Authentication
Credentials differ by deployment.
Cloud uses Basic auth with an Atlassian API token. Both fields are required:
```yaml theme={null}
confluence:
base_url: https://acme.atlassian.net/wiki
deployment: cloud
email: {{ env('CONFLUENCE_EMAIL') }}
api_token: {{ env('CONFLUENCE_API_TOKEN') }}
spaces:
- DATA
```
Self-hosted takes either a personal access token (Bearer auth) or a username and password (Basic auth). Supply one or the other:
```yaml theme={null}
confluence:
base_url: https://confluence.acme.com
deployment: server
personal_access_token: {{ env('CONFLUENCE_PAT') }}
spaces:
- DATA
```
```yaml theme={null}
confluence:
base_url: https://confluence.acme.com
deployment: server
username: {{ env('CONFLUENCE_USERNAME') }}
password: {{ env('CONFLUENCE_PASSWORD') }}
spaces:
- DATA
```
### 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.
| Selector | What it pulls |
| ------------ | ---------------------------------------------------------------------------------------------------- |
| `pages` | Individual pages, given as numeric page IDs or as URLs that carry one. |
| `page_trees` | A page **and all of its descendants**. Use this to take a whole section without listing every child. |
| `labels` | Every page carrying the label. Scope it to one space with `SPACE:label`. |
| `spaces` | A space in full, by its key (`ENG`, `DATA`). |
```yaml theme={null}
confluence:
base_url: https://acme.atlassian.net/wiki
deployment: cloud
email: {{ env('CONFLUENCE_EMAIL') }}
api_token: {{ env('CONFLUENCE_API_TOKEN') }}
pages:
- https://acme.atlassian.net/wiki/spaces/DATA/pages/123456/Metric+Glossary
page_trees:
- 789012
labels:
- DATA:certified
spaces:
- ENG
```
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.
```
your-project/
└── docs/
└── confluence/
├── space=DATA/
│ ├── metric-glossary-123456.md
│ ├── runbooks-789012.md
│ └── runbooks-789012/
│ └── nightly-refresh-789013.md
└── space=ENG/
└── blog/
└── q3-platform-review-345678.md
```
### 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](/nao-agent/chat/admin/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**
Initialize and configure your nao project
Learn how to sync and update your agent's context