IronRAG ↔ Confluence connector

Sync Confluence spaces into IronRAG with configurable routing, auth, and incremental polling.

---

This connector is built on the IronRAG Connector Template and focuses on Confluence-specific behavior:

• Confluence REST API pagination and retries.
• Auth modes: anonymous, basic, bearer, or auto.
• Flexible source selection via CQL + include/exclude space keys.
• Routing facts that let you map different spaces/sections to different IronRAG workspaces/libraries.
• Optional attachment sync as dependent items. Page attachments and inline images now ingest as attached context of their source page rather than as peer documents — they are auto-linked to their page by the SDK (parent_external_key), with no config change required.

Quick start

cd confluence
cp .env.example .env.local
cp routing.yaml.example routing.yaml

uv sync --all-extras
uv run pytest
uv run confluence-connector

Required env vars

CONFLUENCE_BASE_URL=https://confluence.example.com
CONFLUENCE_AUTH_MODE=auto

IRONRAG_BASE_URL=http://localhost:19000
IRONRAG_API_TOKEN=...
ADMIN_BEARER_TOKEN=...

Auth examples:

• Anonymous public Confluence:
  • CONFLUENCE_AUTH_MODE=anonymous
• Basic auth:
  • CONFLUENCE_AUTH_MODE=basic
  • CONFLUENCE_USERNAME=...
  • CONFLUENCE_PASSWORD=... (or CONFLUENCE_TOKEN=...)
• Bearer/PAT:
  • CONFLUENCE_AUTH_MODE=bearer
  • CONFLUENCE_TOKEN=...

Space selection modes:

• All spaces (default): leave CONFLUENCE_SPACE_KEYS empty, or set it to all, any, or *.
• Explicit include-list: CONFLUENCE_SPACE_KEYS=ENG,DOCS,OPS.
• Exclude-list (works with both modes): CONFLUENCE_EXCLUDE_SPACE_KEYS=ARCHIVE,OLD.
• Additional narrowing: CONFLUENCE_CQL=label = "public".

Routing strategy

The adapter emits routing facts such as:

• space / space_key
• space_name
• ancestor_title (list)
• ancestor_id (list)

That allows rules like:

• send space_key=ENG to engineering library;
• send pages under ancestor section Runbooks to ops library.

See routing.yaml.example.

Deploy with Docker Compose

cp .env.example .env.local             # CONFLUENCE_* + IRONRAG_* + ADMIN_BEARER_TOKEN
cp routing.yaml.example routing.yaml   # map spaces/sections → (workspace, library)
docker compose up -d
docker compose logs -f

docker-compose.yml pulls the released image, mounts your routing.yaml read-only, and persists the SQLite cursor in a named volume so a restart ships only the diff. Port 8088 is published on localhost only — put a TLS reverse proxy in front and use it only when running RUN_MODE=webhook/both.

Long-running source items are bounded by SYNC_ITEM_TIMEOUT_SECONDS. IronRAG mutation admission and the post-sweep reaper list call can be bounded separately with IRONRAG_MUTATION_TIMEOUT_SECONDS and REAPER_LIST_TIMEOUT_SECONDS.

Related

• IronRAG — the RAG backend these connectors feed.
• Connector Template — the framework every connector builds on.
• Connectors: Confluence · BookStack · Git Repositories

License

MIT — see LICENSE.