Source connectors

Confluence & Atlassian

Set up Atlassian OAuth, Forge provisioning, and Confluence sync for self-hosted ctxpipe.

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. Save its client ID and secret in that step. On Docker Compose, the ATLASSIAN_* values need an override file (see Docker). 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)

CodeWhat to check
forge_missing_operator_emailGive the email of the Atlassian account that owns the Forge token
forge_auth_failedForge scoped API token (App: Forge) at id.atlassian.com
forge_developer_space_noninteractiveThe 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_failedctxpipe could not find or create the Forge developer space. Retry; contact support with job id
forge_lint_failedBundled app; contact support with job id
forge_deploy_forbiddenAtlassian user cannot deploy this app
confluence_install_forbiddenInstall requires Confluence admin
confluence_install_siteSite host / Confluence product
networkFirewall, DNS, outbound HTTPS
unknownRetry; 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.