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_URLorCTXPIPE_PUBLIC_APP_URLthat 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:
- An install URL saved for this Confluence connection.
- Deployment-wide
CONFLUENCE_FORGE_INSTALL_URL. - 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:
- Link or confirm the GitHub connector.
- In Add to Workspaces, select the Workspaces that receive Confluence content.
- Select the Confluence spaces and pages to ingest.
- Review and merge the pull request that adds
sources/confluence/<name>.mdin 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
Complete the product wizard, choose the scope, and merge the source pull request.
Configure the App that opens source pull requests and receives Confluence content.
Verify public callbacks, secrets, persistence, and recovery.
Monitor connector jobs, logs, and service health.