# Confluence connector (https://docs.ctxpipe.ai/docs/connections/source-connectors/confluence)

The **Confluence connector** mirrors the Confluence spaces and pages that you
select into a [Workspace](/docs/workspaces) repository. ctxpipe does not read
the whole site. You choose what agents can use.

ctxpipe connects to the Confluence site through Atlassian OAuth and the ctxpipe
Forge app. When pages or spaces change, the Forge app tells ctxpipe, and
ctxpipe updates the mirror.

On a self-hosted deployment, the operator provides the Atlassian OAuth app and
the Forge setup first. See
[Self-host Confluence & Atlassian](/docs/self-hosting/confluence-atlassian).

<ConfluenceDataFlowDiagram />

## Data flow

<ConfluenceDataModelDiagram />

## Before you start

You need:

* permission to authorize Atlassian OAuth for the Confluence site;
* permission to install the ctxpipe Forge app on the site, or an Atlassian
  admin who can install it.

<Callout title="Not sure whether you have the right access?">
  Open `admin.atlassian.com`, choose the Confluence site, and check whether you
  can open **Connected apps** and install apps. Atlassian requires organization
  admin or site admin access for this. If you cannot, ask an Atlassian admin to
  install the Forge app. See
  [Atlassian Connected apps](https://support.atlassian.com/organization-administration/docs/managing-an-installed-app/).
</Callout>

## Connect Confluence

<Steps>
  <Step>
    ### Start from Connectors

    Open **Connectors**, choose **Add connection**, then **Atlassian
    Confluence**. The setup wizard tracks each task until the connector is
    ready.

    <ImageSlot title="Start Confluence setup" src="/add-connection-confluence.png" alt="Add Confluence connection from the ctxpipe Connectors page" />
  </Step>

  <Step>
    ### Link your Atlassian account

    Link your Atlassian account with OAuth. This tells ctxpipe which Atlassian
    cloud site you connect. If the account is already linked to another ctxpipe
    organization, the wizard asks you to confirm or cancel.

    <ImageSlot title="Link Atlassian account" src="/link-atlassian-account.png" alt="Link Atlassian account step in the ctxpipe Confluence setup wizard" />
  </Step>

  <Step>
    ### Install the Forge app

    Install the ctxpipe Forge app on the same Atlassian site. The Forge app lets
    ctxpipe read the content that you select, and tells ctxpipe about changes.

    <ImageSlot title="Install the Forge app" src="/install-forge-app.png" alt="Install the ctxpipe Forge app in Atlassian Confluence" />
  </Step>

  <Step>
    ### Add to Workspaces

    Select the Workspaces, then select the spaces and pages in the tree. For
    each space, select all pages or only some. Keep the scope intentional:

    * start with the spaces that your engineering team uses;
    * leave out old or sensitive areas that agents must not rely on;
    * prefer the authoritative docs to duplicates and abandoned pages.

    Choose **Add to Workspaces**, then merge the pull request that adds
    `sources/confluence/<name>.md`. See
    [Add a tool to a Workspace](/docs/connections#add-a-tool-to-a-workspace).
  </Step>
</Steps>

## Source file

For each space, `pages` is `all` or a list of page ids:

```markdown
---
provider: confluence
connection: con_example
spaces:
  - key: ARCH
    pages: all
  - key: OPS
    pages: ["12345", "67890"]
---
```

## Files in the repository

Mirrored pages are under `confluence/<spaceKey>/`, in the page tree of the
space. A page is `<slug>--<pageId>.md`, or `<slug>--<pageId>/index.md` when it
has child pages. Attachments and embedded media are under
`confluence/<spaceKey>/_assets/<pageId>/`. Each asset can be up to 25 MiB, and
each page up to 100 MiB in total. A file that is too large or not safe stays a
link to Confluence. ctxpipe never writes Atlassian download URLs to git.

For problems, see [Troubleshooting](/docs/connections#troubleshooting).