Contextator
ENTR

Sources

Confluence

Indexing Confluence Cloud or Data Center — deployment differences, token types, the private-address boundary, and the Data Center webhook.

Updated:

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.254 included — plus unspecified and multicast addresses, the reserved 240.0.0.0/4 block (which holds 255.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 range fec0::/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.

  1. Edit the source and choose Turn on in the Confluence webhook box; copy the URL and the secret.
  2. The relay receives the Cloud event and sends POST /api/webhooks/confluence/<source-id> with the event’s JSON as the body and X-Hub-Signature: sha256=<HMAC-SHA256 of that exact body>, keyed with the secret. Put the Data Center event name (page_updated, …) in a top-level event field: a body without one queues a run on every delivery, comments and labels included.
  3. 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

Arrow keys to move, Enter to open.