Confluence

For org admins connecting a Confluence wiki as a knowledge source.

Hekkos can index a Confluence space so your team can ask about its wiki pages alongside your code and docs. Connecting is admin-only and lives under Settings → Connections, where GitHub installations and Confluence spaces share one Connections list. This guide covers connecting a space, picking which pages to ingest and at what scope, serving pages according to who may read them, and the optional real-time sync.

Scope is per page, not per space. Connecting a Confluence space is an org-scoped connection (managed under Settings → Connections). What carries a governance scope is the individual pages you pick to ingest — you assign each selected set to your org, an initiative, or a repository (step 2). A whole space is never moved under a project; only the pages you enroll are scoped.

1. Connect a space

You need, from your Atlassian site:

• Base URL — your wiki root, e.g. https://your-org.atlassian.net/wiki.
• Space key — the space to index, e.g. ENG.
• Email + API token — an Atlassian account and a Confluence API token for it. Hekkos uses these to read the space’s pages. The token is stored encrypted and is only ever used to fetch content.

Under Add a source, click Connect a Confluence space to reveal the form, fill it, and click Connect Confluence. The space then appears in the Connections list with a status and a sync chip (the sync state reads as a plain label — Syncing…, Queued, Synced, Sync failed — not a raw status token). Connect as many spaces as you like — each is a separate connection.

Every connected space keeps itself fresh on a schedule (a frequent incremental pass for changed pages, plus a daily full re-walk that also removes deleted pages).

2. Pick which pages to ingest — and scope them

Rather than scanning the whole space from the start, Hekkos lets you choose exactly which pages to ingest and assign each set a scope. On the connected space’s row, open the page picker to:

1. Browse the space’s pages — the picker lists them with a select-all / none control at the top.
2. Tick the pages to ingest — only the pages you select are indexed; unselected pages are left out entirely.
3. Assign a scope — pick Organization, an initiative, or a repository for the selected set, so those pages govern (and answer at) the right level.
4. Save selection — this replaces the space’s current selection.

Editing an existing selection: the picker currently opens with nothing pre-ticked (it does not yet read back your saved picks), and Save replaces the whole set. So when you reopen it to tweak a space you’ve already configured, re-tick every page you want to keep — anything left unticked stops being ingested. A prominent warning in the picker says the same. (Pre-seeding the picker from the saved selection is a planned follow-up once the backend exposes a read endpoint for it.)

Saving an empty selection clears it back to the legacy behavior — a full scan of the whole space. Restricted pages show up in the list but are never selectable: their title is suppressed and they stay gated by the permission-aware rules below, so there’s no restricted content to pick or leak.

How a page’s scope narrows answers

A page’s scope decides where it surfaces in chat and search, following the same cascade as policies: a repository sees pages scoped to the org, to any initiative that contains it, and to itself; an initiative sees org + its own pages; and the default org-wide view sees only org-scoped pages. In other words, scoping a page to an initiative or a repo hides it from general org-wide chat and surfaces it only where it applies.

You set the scope of a chat with the breadcrumb at the top of the app (Org ▸ Initiative ▸ Repo): stand in a repository and the assistant narrows wiki retrieval to that repository’s scope, with a small banner in the composer showing the active scope and a one-click Clear scope back to org-wide. Agents can do the same over MCP by passing an optional repo to the query_knowledge tool. Pages left at Organization scope (or ingested via the legacy full scan) always answer everywhere, exactly as before. GitHub code docs are never narrowed by this — only Confluence pages carry a governance scope.

3. Permission-aware access (optional)

By default, a connected space is indexed as org-internal — every member of your Hekkos org can see its pages in chat and search. If your space uses page-level view restrictions and you want Hekkos to honor them — so a member only sees the restricted pages they could read in Confluence — expand Permission-aware access on the connect form and add:

• Admin API key — an Atlassian Admin/Directory API key (org-admin scope). Hekkos uses it to map each member’s email to their Atlassian account and groups, so it can tell who may read a restricted page.
• Atlassian org id — your Atlassian organization id.

Both are required together (supply neither to index the whole space as org-internal). The admin key is validated against Atlassian when you connect, so a bad key is rejected up front.

With this on, Hekkos stamps each restricted page with the users and groups that may read it, and a member only sees a restricted page in chat/search when they are one of them. The safe direction is always favored: if Hekkos can’t confirm someone may read a page, it hides it — it never shows a page to someone who couldn’t open it in Confluence.

Restricted pages inside a fully-restricted space (a space that isn’t open to everyone) are supported too, including sites that use Confluence’s newer role-based space permissions — but this is gated by an operator setting (CONFLUENCE_RESTRICTED_SPACES, see the configuration reference). Ask whoever runs your Hekkos deployment if you need it.

Permission changes reconcile on a schedule (hourly), so a page that gains or loses a restriction is re-stamped within about an hour even if its content didn’t change.

4. Real-time sync (optional)

Spaces refresh on a schedule by default — usually fine. To push page changes to Hekkos in seconds instead, install the Hekkos app from the Atlassian Marketplace into your Confluence site and link it to your Hekkos org:

1. Under Settings → Connections, in the Real-time sync section (shown once at least one space is connected), click Generate linking token. This gives you a single-use token that expires in 30 minutes.
2. Install the Hekkos app in Confluence and paste the token into its setup page.

That’s it — content edits then sync in near-real-time. A few honest notes:

• Real-time is a freshness accelerator, not a correctness mechanism. The scheduled sync remains the source of truth and the backstop.
• Permission changes are still reconciled on the schedule, not in real time — Confluence doesn’t reliably emit an event when a page’s restriction changes, so page-level access stays fresh via the hourly reconcile above, not the webhook.
• Deploying the Forge app is an operator step; see the configuration reference.

What members see

• A page is shown in chat and search only to members who may read it — org-internal pages to everyone, restricted pages to their allowed users/groups.
• Answers that draw on a wiki page cite it with a stable link back to Confluence.
• Members who aren’t admins can’t connect or disconnect spaces; they just see the results they’re entitled to.

Measured against your code

A connected space isn’t only a place Hekkos reads from to answer questions — its pages are checked against your real code, the same way your in-repo docs are. When a page makes a falsifiable claim about the code — a function signature, an HTTP route, an env var — Hekkos diffs that claim against the real state it extracted from your repositories and, when they disagree, raises a drift finding. Hekkos measures the claim; it never asks you to confirm it.

• Source-tagged findings. A wiki-sourced finding shows a Wiki chip in the repo’s Findings view and links back to the page with Open page in Confluence. It’s attributed to the repository whose code the page describes.
• Fixed in Confluence, not by a PR. These findings have no code fix and no standing PR — the wiki is what’s out of date. Edit the page; Hekkos re-checks it on the next sync and the finding clears.
• Only fully-open pages. Exactly like search and chat, measurement covers only pages readable by everyone in the org. A restricted page is never measured, and if a space or page later becomes restricted its wiki findings resolve on the next run.
• Never the code Trust headline. Wiki drift is tracked on its own honesty count — how many wiki claims disagree with the code — and is deliberately kept out of your code Trust, coverage, and posture numbers. A stale wiki can’t deflate the score your code earned, and a repo’s code drift count stays code-only (wiki drift shows as a separate “+N from Confluence” indicator). See Drift & enforcement.

Disconnecting

Disconnecting a space (the trash icon on its row) stops its pages from syncing and serving. Existing history is kept; re-connect to resume. Its wiki drift findings resolve on the next measurement run (they no longer describe a connected source).