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 Sources 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.

Governance can be rolled back via GOVERNANCE_V2_ENABLED=false; with it off, a connected space falls back to scanning the whole space (the pick+scope picker in step 2 is the default and is hidden when the flag is off).

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 Sources list with a status and a sync chip. 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.

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.

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.