# Confluence & Atlassian (https://docs.ctxpipe.ai/docs/self-hosting/confluence-atlassian)

## Overview

Self-hosted Confluence uses the same connector surface as hosted ctxpipe. But
your deployment owns the Atlassian and Forge configuration. There are two
modes:

* **Managed-style install URL**: give a Forge install URL for the connection
  or deployment. The wizard then opens Atlassian's install flow.
* **Self-hosted provisioning**: the worker creates, deploys, and installs a
  Forge app. It uses a scoped Forge API token and the Confluence site hostname.

Both modes keep connector settings and encrypted credentials on your deployment.

## What you need

* A public `AUTH_BASE_URL` or `CTXPIPE_PUBLIC_APP_URL` that Atlassian can reach.
* A Confluence Cloud site, for example `your-site.atlassian.net`.
* A GitHub connection, and a Workspace that the GitHub App can write to.
* For per-connection OAuth: an Atlassian 3LO app.
* For provisioning: an Atlassian account email and Forge scoped API token.

## 1. Register Atlassian OAuth

If your deployment sets global **`ATLASSIAN_CLIENT_ID`** and
**`ATLASSIAN_CLIENT_SECRET`**, ctxpipe uses that Atlassian app for account linking.
Otherwise, the wizard shows **Register Atlassian OAuth app**. Register a 3LO
app for the Forge connection in the
[Atlassian developer console](https://developer.atlassian.com/cloud/oauth-2-3lo-apps).
Save its client ID and secret in that step. On Docker Compose, the
`ATLASSIAN_*` values need an override file (see
[Docker](/docs/self-hosting/deployment/docker#settings-that-need-an-override-file)).
On AWS CDK, use `connectorSecrets.atlassianClientId` and
`connectorSecrets.atlassianClientSecret`.

Use this callback URL:

`{AUTH_BASE_URL}/api/v1/integrations/atlassian/callback`

ctxpipe encrypts per-connection credentials and does not return the client secret
from connector metadata.

## 2. Install or provision Forge

The wizard resolves the Forge install path in this order:

1. An install URL saved for this Confluence connection.
2. Deployment-wide **`CONFLUENCE_FORGE_INSTALL_URL`**.
3. No install URL, which shows the self-hosted provisioning form.

Provisioning runs `forge register`, `forge deploy`, and `forge install` through
a durable worker job. The generated Forge app uses your public API origin for
its remote callback.

The Forge app requires `read:attachment:confluence` to clone page attachments.
After you upgrade the app manifest that you have, deploy the new Forge version.
Complete Atlassian's permission upgrade. A refresh of the app-system token alone
does not grant the new scope. ctxpipe stores assets in the Workspace repository.
The limits are 25 MiB for each file and 100 MiB for each page. The worker removes
credentials from media redirects. It never saves Atlassian download URLs.

### Allowed Forge apps

ctxpipe accepts a Forge call only from the Forge app of that Confluence
connection. The allowed app is one of these:

* The app ID that the connection saved. Provisioning saves this ID before
  `forge install`.
* When the connection has no saved app ID: the app ID in the install URL of the
  connection, the app ID in **`CONFLUENCE_FORGE_INSTALL_URL`**, or the hosted
  ctxpipe app. The first install event saves the ID of the app.

## 3. Finish the connector

After Atlassian is linked and Forge is installed:

1. Link or confirm the GitHub connector.
2. In **Add to Workspaces**, select the Workspaces that receive Confluence
   content.
3. Select the Confluence spaces and pages to ingest.
4. Review and merge the pull request that adds `sources/confluence/<name>.md`
   in each Workspace repository.

ctxpipe then syncs Confluence content into each selected Workspace repository.
The content goes through the same indexing and graph ingestion path as other
source material.

## Error codes (provision)

| Code                                   | What to check                                                                                                                                |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `forge_missing_operator_email`         | Give the email of the Atlassian account that owns the Forge token                                                                            |
| `forge_auth_failed`                    | Forge scoped API token (App: Forge) at id.atlassian.com                                                                                      |
| `forge_developer_space_noninteractive` | The Atlassian account has no Forge developer space, and the job cannot create one. Create it in the Atlassian developer console, then retry. |
| `forge_developer_space_ensure_failed`  | ctxpipe could not find or create the Forge developer space. Retry; contact support with job id                                               |
| `forge_lint_failed`                    | Bundled app; contact support with job id                                                                                                     |
| `forge_deploy_forbidden`               | Atlassian user cannot deploy this app                                                                                                        |
| `confluence_install_forbidden`         | Install requires Confluence admin                                                                                                            |
| `confluence_install_site`              | Site host / Confluence product                                                                                                               |
| `network`                              | Firewall, DNS, outbound HTTPS                                                                                                                |
| `unknown`                              | Retry; contact support with job id                                                                                                           |

## Environment (operators)

* **`AUTH_BASE_URL` / `CTXPIPE_PUBLIC_APP_URL`** - public origin for API and callback URL registration.
* **`ATLASSIAN_CLIENT_ID` / `ATLASSIAN_CLIENT_SECRET`** (optional) - global Atlassian OAuth app for account linking. If unset, use per-connection 3LO in the wizard.
* **`CONFLUENCE_FORGE_INSTALL_URL`** (optional) - deployment-wide fallback for
  the **Install** step when a connection does not have its own install URL.

## Related pages

<Cards>
  <Card title="Confluence user guide" href="/docs/connections/source-connectors/confluence" description="Complete the product wizard, choose the scope, and merge the source pull request." />

  <Card title="GitHub" href="/docs/self-hosting/github" description="Configure the App that opens source pull requests and receives Confluence content." />

  <Card title="Production readiness" href="/docs/self-hosting/production-readiness" description="Verify public callbacks, secrets, persistence, and recovery." />

  <Card title="Operations" href="/docs/self-hosting/operations" description="Monitor connector jobs, logs, and service health." />
</Cards>
