#Confluence Integration

DevBoy tools provide integration with Atlassian Confluence for reading and updating internal documentation through AI assistants. Both Confluence Cloud and Confluence Server / Data Center are supported. Confluence is the first provider in the KnowledgeBase category.

#Deployment flavors

DevBoy supports two Confluence flavors:

Flavor can be set explicitly with confluence.flavor. When omitted, DevBoy auto-detects Cloud for *.atlassian.net URLs and otherwise defaults to self_hosted.

#Authentication

Authentication depends on the deployment flavor.

#Confluence Cloud

Confluence Cloud supports:

#Self-hosted / Server / Data Center

Self-hosted Confluence supports:

#Configuration

#Basic configuration

# Set Confluence base URL
devboy config set confluence.base_url https://wiki.company.com

# Optional: force flavor instead of relying on auto-detection
devboy config set confluence.flavor self_hosted

# Optional: prefer the newer Data Center API where available
devboy config set confluence.api_version v2

# Optional: set a default space hint for this context
devboy config set confluence.space_key ENG

# For bearer token / PAT auth
devboy config set-secret confluence.token <token>

#Basic auth configuration

devboy config set confluence.base_url https://wiki.company.com
devboy config set confluence.username user@company.com
devboy config set-secret confluence.token <password-or-token>

#Confluence Cloud configuration

# Cloud is auto-detected for *.atlassian.net, but can be explicit
devboy config set confluence.base_url https://team.atlassian.net
devboy config set confluence.flavor cloud

# Optional: cache the Atlassian cloud id
devboy config set confluence.cloud_id cloud-123

#Confluence Cloud with basic auth

devboy config set confluence.base_url https://team.atlassian.net
devboy config set confluence.flavor cloud
devboy config set confluence.username user@company.com
devboy config set confluence.cloud_id cloud-123
devboy config set-secret confluence.token <atlassian-api-token>

confluence.cloud_id is required for Cloud basic auth. For Cloud bearer auth, DevBoy can discover it automatically from Atlassian accessible-resources.

#Confluence Cloud OAuth setup

devboy config set confluence.base_url https://team.atlassian.net
devboy config set confluence.flavor cloud
devboy config set confluence.client_id <oauth-client-id>
devboy config set confluence.redirect_uri http://localhost:8787/callback

Then:

devboy config confluence-oauth url
devboy config confluence-oauth exchange --code <authorization-code>

To refresh the stored access token later:

devboy config confluence-oauth refresh

The access token and refresh token are stored in the keychain. The current runtime behavior expects a valid stored access token; token refresh is an explicit CLI action rather than an automatic background refresh.

#Configuration file

Settings are stored in ~/.config/devboy-tools/config.toml:

[confluence]
base_url = "https://wiki.company.com"
flavor = "self_hosted"
api_version = "v2"
username = "user@company.com"
space_key = "ENG"

Cloud example:

[confluence]
base_url = "https://team.atlassian.net"
flavor = "cloud"
cloud_id = "cloud-123"
client_id = "atlassian-client-id"
redirect_uri = "http://localhost:8787/callback"
space_key = "ENG"

The token is stored separately in the OS keychain for security.

#Environment variables

export DEVBOY_CONFLUENCE_TOKEN=your-token

#API version selection

Confluence self-hosted installations are not uniform. DevBoy supports:

Use v2 for newer Data Center installs when available. If a v2 endpoint is missing, DevBoy falls back to the classic REST API for supported operations.

For Confluence Cloud, DevBoy uses Atlassian Cloud routing and the Cloud API shape automatically. api_version is mainly relevant to self-hosted installations.

#MCP tools

Once configured, the following MCP tools are available:

#Tool behavior

#Page content format

Confluence stores content in its own storage format. DevBoy handles conversion for agent-friendly workflows:

• Reads return page content as Markdown.
• Writes accept contentType values of markdown, html, or storage.
• markdown is the best default for agent-generated docs.
• Confluence Cloud reads can arrive as Atlassian Document Format (ADF); DevBoy converts ADF to Markdown for agent consumption.
• Confluence Cloud writes are converted back into a Cloud-compatible representation automatically.

#Labels

create_knowledge_base_page and update_knowledge_base_page support a labels parameter:

• On create, labels are added after the page is created.
• On update, labels replace the previous set when the parameter is provided.
• If labels is omitted on update, existing labels are left unchanged.

#Optimistic locking

update_knowledge_base_page supports an optional version field:

• If provided, DevBoy verifies the current page version before writing.
• If the current version differs, the tool returns a conflict error instead of overwriting newer content.

#Search and CQL

search_knowledge_base supports two modes:

• Free-text search: pass query and optionally spaceKey
• Raw CQL: set rawQuery: true and provide a full Confluence query

Example:

{
  "query": "label = \"adr\"",
  "rawQuery": true
}

#Example usage

#List pages in a space

{
  "spaceKey": "ENG",
  "limit": 10
}

#Create a page from Markdown

{
  "spaceKey": "ENG",
  "title": "ADR-012: Event Routing",
  "content": "# Decision\n\nWe route events through the queue.",
  "contentType": "markdown",
  "labels": ["adr", "architecture"]
}

#Update a page with version checking

{
  "pageId": "123456",
  "content": "## Updated\n\nNew content here.",
  "contentType": "markdown",
  "version": 7,
  "labels": ["adr", "accepted"]
}

#Testing

Verify your Confluence configuration:

devboy test confluence

This checks connectivity against the spaces endpoint and confirms that the configured auth method can reach the API.

Cloud-specific behavior:

• Cloud bearer auth validates Atlassian accessible-resources discovery and then probes the Cloud v2 spaces endpoint.
• Cloud basic auth requires confluence.cloud_id and probes the Cloud v2 spaces endpoint directly.
• Self-hosted keeps the existing /rest/api / /api/v2 connectivity path.

#Proxy support

Confluence self-hosted instances are often only reachable through internal routing or gateway services. DevBoy supports proxy-mode provider wiring for Confluence using the same proxy mechanism used for other self-hosted providers.

Use this when:

• the Confluence base URL is not directly reachable from the assistant runtime
• authentication must be injected by a gateway
• custom routing headers are required

#Troubleshooting

#"401 Unauthorized" error

• Verify the token is valid and not expired
• If using basic auth, check that confluence.username is set correctly
• If using self-hosted bearer auth, make sure the token is a Confluence PAT and not a Jira token
• If using Confluence Cloud bearer auth, confirm the token is an Atlassian OAuth access token with Confluence scopes

#"404 Not Found" error

• Use the site root as base_url, for example https://wiki.company.com
• For Cloud, use the site root such as https://team.atlassian.net
• Do not include /rest/api, /wiki/rest/api, or /api/v2 in base_url
• If api_version = "v2" is configured, your instance may not expose all v2 endpoints; DevBoy will fall back where supported

#"explicit confluence.cloud_id" error

• This only applies to Confluence Cloud basic auth
• Set confluence.cloud_id explicitly
• With Cloud bearer auth, DevBoy can discover cloud_id automatically from Atlassian

#"space not found" error

• Verify the spaceKey is the short Confluence space key, not the display name
• Confirm the authenticated user can access that space

#Version conflict on update

• Another user or automation updated the page after you read it
• Re-fetch the page, inspect the latest content, then retry with the new version

#Markdown formatting looks different in Confluence

• Confluence storage format is not identical to Markdown
• Basic headings, paragraphs, links, lists, and code blocks are handled, but some Confluence-specific macros may not round-trip exactly