Index a Confluence Cloud site or a Confluence Data Center instance: every space the account can read, or exactly the spaces you name, rendered from Confluence’s storage format to Markdown.
Adding one
Add source → Confluence
| Field | Notes |
|---|---|
| Name | The mount prefix. Immutable |
| Deployment | Confluence Cloud or Confluence Data Center 7.9 or later. Not detected — the two authenticate differently, and a wrong guess would send the credential the wrong way |
| Site URL | Cloud: with its /wiki path, e.g. https://acme.atlassian.net/wiki. Data Center: the address your users open, with its context path if it has one, e.g. https://intranet.example.com/confluence |
| Account e-mail | Cloud only — the Atlassian account the API token belongs to |
| API token / Personal access token | Cloud: an API token. Data Center: a personal access token. Stored encrypted with SECRET_KEY, never shown again and never returned by the API |
| Spaces | Space keys, one per line (ENG, OPS). Leave empty to index every space the account can read |
Once the source is saved, press Test on its row (or Test connection in its Edit dialog): it checks the site, the credential and the scope without indexing anything. The account’s own permissions are the outer boundary either way: Contextator never sees a page the account cannot.
Cloud or Data Center
- Cloud is the REST API under
https://<site>.atlassian.net/wiki, authenticated with an Atlassian account e-mail and an API token. - Data Center 7.9 and later is the REST API under
<base URL>/rest/api, authenticated with a personal access token sent as a bearer — there is no e-mail. Before any credential is sent, the server’s version is read from its anonymous application manifest; an older release, a version that cannot be read, or a server that is not Confluence is refused with the version named, on Test connection and on sync. - Confluence Server, the product line before Data Center, is not supported. If that is what you run, export the space and add it as an Upload source instead.
A Data Center on the internal network
The base URL is typed by an editor and the server connects to it carrying the source’s token, so where a Confluence source may connect is bounded:
- Always refused: loopback and link-local addresses — the cloud metadata address
169.254.169.254included — plus unspecified and multicast addresses, the reserved240.0.0.0/4block (which holds255.255.255.255), and the IPv6 forms that carry one of those IPv4 addresses (IPv4-mapped, translated, compatible and NAT64). No setting lifts these. - Refused unless allowed: private addresses —
10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,100.64.0.0/10(shared address space, as used by carrier-grade NAT),198.18.0.0/15(benchmarking),fc00::/7, and the deprecated site-local rangefec0::/10.
If your Data Center resolves to a private address, list its host in SOURCE_ALLOWED_HOSTS and
restart:
SOURCE_ALLOWED_HOSTS=wiki.corp.example
The check runs on the address the connection actually uses — after DNS, and again on every redirect — so neither a public-looking name that resolves inward, nor a redirect to an internal address, gets past it. A refusal names the rule on the source’s row and in the Test message, for example:
refused: `wiki.corp.example` resolves to a private address; list `wiki.corp.example` in SOURCE_ALLOWED_HOSTS to allow it
No request — and so no token — is sent in that case. The list lifts only the private-address rule, and
only for the names on it; there is no switch that turns the check off entirely. SOURCE_ALLOWED_HOSTS
is set in .env, alongside the rest of the shipped
.env.example.
Before 0.6.0 this list was called CONFLUENCE_ALLOWED_HOSTS. That name was removed in 1.0.0: a non-empty value now stops the
server from starting, with a message that names SOURCE_ALLOWED_HOSTS. Move its hosts to SOURCE_ALLOWED_HOSTS before upgrading;
it also admits the S3 and GitHub Enterprise Server sources.
What a page becomes
Each page is one Markdown file, nested by its ancestry: <name>/<space key, lowercased>/<parent page>/<page>.md,
where each page folder and file name is the title as a slug plus the first eight characters of the page id.
Only pages are indexed. Blog posts are not, and blog events from a webhook are ignored.
Confluence’s storage format is XHTML plus Confluence’s own ac: and ri: namespaces. It goes through
the same HTML→Markdown transform .html files do — see Content Types — so
tables, code blocks, task lists and admonitions survive as structure.
- Macros are unwrapped. The prose inside an expand or a panel is indexed; the macro’s own configuration is not.
- Admonitions keep the word that made them admonitions, so a note still reads as a note.
- Code blocks survive. They live inside
<![CDATA[…]]>, which an ordinary HTML parser drops on the floor — that is handled before the transform runs, not after.
How it stays fresh
A scheduled check of a Confluence source is one request: one CQL search over exactly the spaces the run indexes, reporting how many pages there are and when the newest was touched. If neither number moved, nothing is fetched.
On Data Center, a signed webhook can start a sync as soon as a page changes — see Push Webhooks. It complements the sync interval; it does not replace it. Confluence Cloud cannot send one without a Forge or Connect app, so there the sync interval is how a source stays fresh — see Indexing.
A relay for Confluence Cloud
Contextator does not ship one, and the Cloud webhook stays out of scope. If you want faster updates on Cloud anyway, the part Contextator offers is the receiving end, and it does not care where the delivery came from: a small service of your own, fed by a Forge or Connect app on the Cloud side, can post to the same endpoint a Data Center instance would.
- Edit the source and choose Turn on in the Confluence webhook box; copy the URL and the secret.
- The relay receives the Cloud event and sends
POST /api/webhooks/confluence/<source-id>with the event’s JSON as the body andX-Hub-Signature: sha256=<HMAC-SHA256 of that exact body>, keyed with the secret. Put the Data Center event name (page_updated, …) in a top-leveleventfield: a body without one queues a run on every delivery, comments and labels included. - Anything signed wrongly is refused with
401 invalid_signature; the rules for which events queue a run and the minimum interval between runs are the ones in Push Webhooks.
The relay is yours to build, host and secure, and Contextator does not test it. Keep the sync interval on: a delivery is a hint to look soon, never a record of what changed.
Limits worth knowing
- One source indexes at most 5 000 pages by default. The ceiling is
CONFLUENCE_MAX_PAGES(1 to 100 000, set per instance — see Configuration). A larger wiki is indexed up to the ceiling and the run says so, in those words, on the source’s row. Split it across several sources by naming fewer spaces on each. - If one of several named spaces stops answering, nothing is deleted. A renamed space key, or a permission withdrawn from the account, reads to the API as a space with no pages rather than as an error — so a configured space that held documents a moment ago and offers none now fails the sync, naming the space, instead of quietly deleting its documents. With Spaces left empty there is no list of what should be there and that check cannot be made.
- A page that cannot be rendered is a complaint, not a failed sync. A request that failed is a failed sync. The two are kept apart so a rate-limited first pull cannot report success over a third of a missing wiki.
Common problems
| Symptom | Cause and fix |
|---|---|
| Test connection refused, naming a version | The server is older than 7.9, its version could not be read, or it is not Confluence at all |
| Refused: resolves to a private address | List the Data Center’s host in SOURCE_ALLOWED_HOSTS and restart |
| A configured space fails the sync, naming the space | The space key was renamed, or the account’s permission on it was withdrawn |
| A page is missing but the sync succeeded | It was refused as unrenderable rather than causing a failed sync — check the source’s row for the complaint |
| Nothing indexed, Spaces left empty | The account has read permission on no space |
Test connection or sync answers 404 naming the site URL |
The site URL is missing its /wiki path (Cloud) or its context path (Data Center) — the error names which one to check |