CodeDoc AI for Confluence — Documentation

Complete Setup & User Guide

1. Overview

CodeDoc AI for Confluence automatically generates documentation from your source code repositories and publishes it directly to Confluence. You bring your own AI provider (BYOK — Bring Your Own Key), connect your Git hosting, and the app takes care of the rest: analyzing your codebase, generating structured documentation in Confluence-native format, and keeping it up to date.

Key capabilities:

• Multi-provider AI — Works with Anthropic (Claude), OpenAI (GPT), and Google (Gemini).
• Multi-provider Git — Supports GitHub, GitLab, Bitbucket, and Azure DevOps (cloud).
• 8 documentation presets — From developer deep-dives to management overviews, compliance audits, and onboarding guides.
• 10 languages — Generate documentation in English, German, French, Spanish, Italian, Portuguese, Japanese, Chinese, Korean, or a custom language.
• Automatic triggers — Run jobs manually, on every commit/merge via webhook, or on a daily/weekly/monthly schedule.
• AI-powered file selection — A two-pass system where the AI first identifies the most relevant files, then generates documentation from those files only.
• Generation activity tracking — Monitor your documentation generation history with charts (7 days, 4 weeks, 12 months).

2. How It Works

1. Connect — Add your AI API key and Git access token in the setup wizard.
2. Add Repositories — Browse or paste the URL of the repositories you want to document.
3. Create a Job — Select repositories, choose a documentation preset, pick a language, set a trigger, and choose the Confluence space where the page will be created.
4. Generate — The app reads your code from Git, sends it to your AI provider, receives the documentation, and publishes it as a formatted Confluence page.

Every generation is tracked with token usage, file count, AI model used, and a direct link to the created Confluence page.

3. Example Output

Here is what generated documentation looks like in Confluence. These pages were created automatically from a Terraform infrastructure-as-code repository using the Developer Documentation preset.

Overview & Tech Stack

The AI generates a structured overview with a technology table listing all frameworks, tools, and cloud services detected in the codebase.

Auto-generated overview with tech stack table — versions, roles, and descriptions extracted from code

Architecture & Key Modules

Complex architectures are broken down into core principles, data flow descriptions, and module-by-module documentation with file references.

Architecture section with core principles, component interaction, and key modules

API Reference & Dependencies

The AI documents APIs, configuration outputs, and software dependencies including version ranges and installation requirements.

API reference with code examples and dependency list

4. Installation

5. Initial Setup (Wizard)

The setup wizard has two steps: connecting an AI provider and connecting a Git provider. Both require an API key or access token from the respective service.

Step 1: Connect AI Provider

CodeDoc AI uses a Bring Your Own Key (BYOK) model. You need an API key from one of the supported providers. The app never stores your source code — it sends it directly from Git to the AI provider using your key.

Where to get your API key:

• Anthropic — console.anthropic.com/settings/keys
• OpenAI — platform.openai.com/api-keys
• Google AI (Gemini) — aistudio.google.com/apikey

Step 2: Connect Git Provider

Connect your Git hosting service so the app can read your repositories. You need a personal access token or repository access token with read permissions.

Creating Access Tokens

Each Git provider has its own way of creating tokens. Below is a brief summary — follow the link for full instructions from the provider.

6. Adding Repositories

After setup, go to the Repositories tab to add the repositories you want to document.

Option A: Browse Repositories

1. Click Browse Repos.
2. If you have multiple Git providers configured, select which one to browse.
3. Use the search field to filter by name.
4. Check the repositories you want to add.
5. Click Add Selected.

Option B: Add by URL

1. Click Add URL.
2. Paste the full repository URL (e.g. https://github.com/org/repo).
3. Set the branch to document (default: main).
4. Click Add. The app validates access before adding.

This method works for all token types and is the only option when using Bitbucket Repository Access Tokens (which are scoped to a single repository).

7. Creating Documentation Jobs

A job defines what to document, how to format it, and where to publish it. Go to the Jobs tab and click Create Job.

Job creation: select repositories, preset, language, and trigger

Documentation Presets

Presets control the structure, tone, and depth of the generated documentation. Each preset produces a different Confluence page layout tailored to its audience.

Trigger Types

Each job has a trigger that determines when it runs.

Webhook Setup (Detailed)

Webhook triggers allow your documentation to automatically regenerate when code changes. The app provides a single Webhook URL that works for all jobs. You add this URL to your Git repository's webhook settings, and the app matches incoming events to the correct jobs by repository URL and branch.

Webhook URL displayed when selecting On Commit or On Merge trigger

Supported Webhook Events per Provider

The app processes the following Git events. Configure your webhook to send only the events you need:

Step-by-Step: Adding a Webhook

Scheduled Triggers (Detailed)

Scheduled triggers let your documentation regenerate automatically on a recurring basis without any webhook configuration. Three schedule types are available:

Upcoming scheduled jobs with countdown timer and last run time

File Selection & Analysis

Before generating documentation, the app analyzes your repository to determine which files to include. You have several options:

Analysis preview showing file count, token estimate, and AI-selected files

• All files — Every code file in the repository (or filtered path) is sent to the AI.
• AI-selected — Click "Select with AI" and the AI analyzes file names and structure to pick the most relevant files. You can then lock the selection (fixed for every run) or leave it dynamic (re-selected each time).
• Manual selection — Check/uncheck individual files in the analysis preview.
• Path filter — Restrict analysis to a subdirectory (e.g. /src or /backend).
• Include/Exclude patterns — Use glob patterns to fine-tune which files are included. For example, exclude **/*.test.ts or include only src/**.

The analysis preview shows the total file count, code file count, and estimated token usage before you run the job. Your file selection is saved with the job and restored when you edit it.

Advanced: Custom File Filters

Expand the Advanced: Custom file filters section to fine-tune exactly which files are included or excluded using glob patterns.

Advanced file filters — exclude test files and restrict to specific directories

• Exclude patterns — One pattern per line. Files matching any of these patterns are removed from the file list before analysis. Example: **/*.test.ts, **/*.spec.js, migrations/**.
• Include patterns — One pattern per line. Files matching these patterns are always kept, even if they also match an exclude pattern. Include patterns act as an override for excludes — they do not restrict the total file list to only matching files. Example: src/**, lib/**.

Both fields use glob syntax: * matches any filename characters (not path separators), ** matches any path depth including subdirectories. Leave both fields empty to use the smart defaults (common build artifacts, lock files, and binary files are already filtered automatically).

Common Pattern Examples

Output Token Limit

Under Advanced AI Settings, you can set a maximum output token limit (default: 8192). This controls the length of the generated documentation — not the input. Increase this for comprehensive presets or very large codebases.

Confluence Target

Each job publishes to a specific Confluence space. You can optionally select a parent page to nest the documentation under an existing page, or choose "Root (no parent)" to create a top-level page.

When you run the same job again, the existing Confluence page is updated in place — no duplicate pages are created.

Approval Workflow

Enable "Require approval before publishing" when creating or editing a job to activate the review workflow. When enabled, generated documentation is not published immediately — instead, it is saved as a visible Confluence page with a [DRAFT] prefix in the title, and the job enters a Pending Review state.

The approval workflow is available on both the Dashboard (recent jobs list) and the Jobs tab (full job table). The Dashboard also shows a Pending Review counter tile so you can see at a glance how many drafts are awaiting approval.

8. Custom Presets

Custom Presets let you save a complete documentation configuration as a named, reusable template. Instead of re-configuring documentation style, language, file filters, and output settings for every new job, you create a preset once and load it with one click.

Presets tab — create, edit, duplicate, and delete reusable documentation configurations

What a Preset Stores

Each preset saves the following configuration:

• Documentation Type — One of the 8 built-in presets (Developer Documentation, Management Overview, etc.) or Custom with your own AI instructions.
• Custom Instructions — When using the Custom type, your prompt is stored verbatim and sent directly to the AI as the sole instruction.
• Output Language — The language the generated documentation is written in.
• Exclude Patterns — File glob patterns to always skip (e.g. *.test.js, vendor/**).
• Max Output Tokens — Controls the maximum length of the generated documentation.

Creating and Managing Presets

Open the Presets tab in the CodeDoc AI dashboard. Only Admins can create, edit, or delete presets — all users can load them when creating jobs.

Use Edit to update an existing preset, Duplicate to create a copy as a starting point, and Delete to remove one.

Using Presets in a Job

When creating a new job, a Load from saved preset dropdown appears at the top of the form (only visible if at least one preset exists). Selecting a preset instantly fills in all matching fields — you can then adjust any individual setting before saving the job.

9. Dashboard

The Dashboard is the first screen you see when opening CodeDoc AI. It provides an overview of your documentation activity.

Dashboard with generation activity chart and quick-run job list

• Generation Activity Chart — Visualizes your generation history over 7 days, 4 weeks, or 12 months. Shows completed (green) and failed (red) runs.
• Your Jobs — Quick overview of all jobs with their last run status and a "Run" button to trigger manual generation directly from the dashboard. Jobs with Pending Review status show additional View Draft, Publish, and Discard buttons inline.
• Quick Stats — Total generations, active jobs, connected repositories, and Pending Review count at a glance. The Pending Review tile appears in red when drafts are awaiting approval.

10. Queue & Generation History

The Queue & History tab shows everything that's running, queued, completed, or failed.

Active Queue

Shows jobs currently being processed or waiting in line. Each entry displays the job name, a spinner while running, and a Cancel button to remove it from the queue.

Generation History

Complete generation log with status, model, file count, and token usage

A complete log of every documentation generation with the following details:

• Job — Which job triggered the generation.
• Status — One of four values:
  • Completed — Documentation was generated and published successfully.
  • Pending Review — The job uses the approval workflow and the draft is awaiting review.
  • Approved — The draft was reviewed and published. Click the green Approved badge to see who approved it and when.
  • Failed — Generation failed. Click the red Failed badge to see the full error message.
• AI Provider & Model — Which AI service and model were used.
• Files — Number of files analyzed (e.g. "42/128" means 42 selected out of 128 total).
• Method — How files were selected: "AI-selected", "Auto-sorted", or "All files".
• Tokens — Total input + output tokens consumed (relevant for cost tracking).
• Link — Direct link to the generated Confluence page.

Use Clear History to remove all history entries. This does not delete the generated Confluence pages.

Upcoming Scheduled Jobs

When you have jobs with scheduled triggers, this section appears automatically and shows the next run time with a countdown (e.g. "in 3h 45m"), the schedule description, and when the job last ran.

11. Settings

The Settings tab lets you manage all configuration after initial setup.

AI Provider

View your current AI provider and model, or switch to a different one. When you change providers or keys, the app validates the connection and fetches available models. Click Refresh Models to discover newly released models from your provider.

Git Providers

You can connect multiple Git providers simultaneously — for example, a work GitHub and a personal GitLab. Each provider is listed with its type, display label, connected user, and date added.

• Click Add Provider to connect an additional Git service.
• Click Remove to disconnect a provider (you cannot remove the last one).

Webhook Configuration

The Settings page displays your Webhook URL — a single URL that works for all your webhook-triggered jobs. Add this URL to any repository's webhook configuration in your Git provider. The app automatically matches incoming events to the correct jobs based on the repository URL and branch.

Generation Limits

Fine-tune how the app handles large repositories:

• Max files per job — Maximum number of files sent to the AI in a single generation (default: 50, range: 5–200).
• Input token budget — Maximum total input tokens per generation. Limits the total code sent to the AI to control costs (default: 120,000, range: 30,000–500,000). Keep in mind that this interacts with your chosen model's context window — going beyond the model's limit will result in an API error.

File contents are transmitted in full to your AI provider. No per-file size truncation is applied — the input token budget is the relevant limit for controlling how much code is sent in total.

12. Supported Providers

AI Providers

Git Providers

13. Trial & Licensing

CodeDoc AI is a paid app with a 30-day free trial. During the trial, all features are fully available — there is no difference between trial and paid subscription. After 30 days, a subscription is required to continue using the full feature set.

Teams with up to 10 users on Atlassian's community plan receive the app at no cost with the same full feature set.

Full Feature Set (Trial & Subscription)

• Unlimited repositories, jobs, and runs per day
• All 8 documentation presets + Custom presets
• All 10 output languages
• All 3 AI providers (Anthropic, OpenAI, Google) + all 4 Git providers
• AI-powered file selection
• Approval workflow (review before publish)
• Webhook and scheduled triggers
• Multiple Git providers
• Role-based access control

Free Plan (after trial expires)

If the trial expires without purchasing a subscription, the app switches to the free plan:

• 1 job — your existing job continues to work
• Unlimited repositories, runs per day, and all trigger types (manual, webhook, scheduled)
• All presets, AI providers, output languages, and core features remain available

14. Access Control

CodeDoc AI includes a built-in role system that controls who can access the app and what they can do. Confluence Administrators always have full access. For all other users, access is granted by assigning Confluence groups to one of two roles.

Roles

Configuration

Access is managed entirely through Confluence groups — you assign groups to roles, and manage group members in the native Confluence Admin UI. This means you never need to touch the app when users join or leave; just manage the groups in Confluence as you normally would.

1. Open CodeDoc AI and go to the Permissions tab (visible to Administrators only).
2. Under Administrator Groups, search for the group(s) whose members should have admin access and click + Add.
3. Under Job Operator Groups, add the group(s) whose members should be able to create and run jobs.
4. To manage group members, go to Confluence Settings → Groups and add or remove users there.

Permissions tab — two dedicated groups assigned to their respective roles. The current user's role (Administrator) is shown in the top-right corner next to the AI provider and model.

The current user's role is always visible in the top-right corner of the app, next to the AI provider and model badges. This makes it easy to confirm at a glance which level of access you have.

15. Data Processing & Privacy

Understanding how your data flows through CodeDoc AI:

1. The Atlassian Forge runtime (hosted on Atlassian's infrastructure) fetches your source code from your Git provider using your access token.
2. The Forge runtime sends the source code to your chosen AI provider using your API key.
3. Documentation is generated by the AI and returned to the Forge runtime.
4. The Forge runtime creates or updates a Confluence page with the generated documentation via the Atlassian API.

• All data transfers are encrypted with TLS.
• The app runs entirely within the Atlassian Forge runtime — Atlassian's infrastructure acts as the intermediary for all data flows. No additional external servers beyond your Git and AI providers are involved.
• API keys and access tokens are stored in Forge encrypted storage within your Confluence instance.
• No analytics or telemetry data is collected beyond what Atlassian provides by default.

For full details, see our Privacy Policy.

16. Troubleshooting

Generation failed: "A Confluence page with this title already exists"

Confluence requires page titles to be unique per space. If a page with the same name as your job already exists in the target space at a different location, the generation will fail. Solutions:

• Rename the job — Edit the job and choose a unique name.
• Rename or delete the conflicting page — In Confluence, rename or move the existing page that is causing the conflict.

The app now warns you about this proactively: when creating or editing a job, a warning appears if a conflict is detected before you save. Jobs with known conflicts show a ⚠ Title conflict badge under the job name.

Generation failed: "AI response was empty or invalid"

This usually means the AI model returned an empty or malformed response. Common causes:

• Token budget too low: If the input token budget is set too low, the AI may not receive enough code to generate meaningful documentation. Increase the input token budget in Settings → Generation Limits.
• Output token limit too low: Increase the max output tokens in the job's Advanced AI Settings (default: 8192). Comprehensive presets may need 12000–16000 tokens.
• Model limitations: Some smaller/cheaper models may struggle with very large inputs. Try a more capable model (e.g. switch from Haiku to Sonnet, or from gpt-4o-mini to gpt-4o).

Generation failed: XHTML parsing error

The AI sometimes produces markup that isn't valid Confluence XHTML. The app includes an automatic XHTML repair engine that detects and fixes broken tags, unclosed elements, and invalid macro syntax. If the error persists after the automatic repair and 3 retries, the app falls back to a simplified format (plain text with headings) to ensure the page is always created. No action required on your part — just re-run the job.

Generation failed: "Rate limit exceeded" (429 error)

Your AI provider is rate-limiting requests. The app automatically retries up to 3 times with increasing delays (3s, 8s, 15s). If the error persists:

• Wait a few minutes and try again.
• Check your AI provider's dashboard for rate limit quotas.
• Consider upgrading your AI provider plan for higher rate limits.
• Reduce the number of files sent to the AI by using AI-powered file selection or exclude patterns.

Generation failed: "Insufficient funds" / "Quota exceeded"

Your AI provider account has no remaining credits. Top up your balance:

• Anthropic: console.anthropic.com/settings/billing
• OpenAI: platform.openai.com billing
• Google AI: Gemini has a free tier. If you exceed it, check AI Studio for quota details.

Generation failed: "Request too large" / "Context length exceeded"

The combined source code exceeds the AI model's maximum input size. Solutions:

• Use AI-powered file selection to reduce the number of files sent.
• Lower the input token budget in Settings → Generation Limits.
• Add exclude patterns to skip large or irrelevant files (e.g. **/*.min.js, **/vendor/**, **/*.lock).
• Restrict the path to a subdirectory (e.g. /src) instead of the entire repository.
• Switch to a model with a larger context window (e.g. Claude Sonnet, GPT-4o, Gemini Pro).

Webhook not triggering: "Event is not supported"

You configured a webhook event type that the app doesn't recognize. See the supported events table above. Only push and pull_request/merge_request events are processed. Other events (fork, issue, comment, etc.) are ignored.

Webhook not triggering: Job not found for repository

The webhook fires correctly but no job is matched. Check:

• The repository URL in the webhook payload must match the repository URL configured in the job (including protocol and path).
• The branch in the webhook payload must match the branch configured for the job.
• The job's trigger must be set to On Commit or On Merge (not Manual or Scheduled).

Bitbucket: "Token is invalid or not supported for this endpoint"

You are likely using an Atlassian Account API token (without scopes). Bitbucket requires either:

• A Repository Access Token — created in Repository settings → Access tokens. Works with just the token value.
• An API Token with scopes — created in Account settings → Security → "Create API token with scopes" → select Bitbucket → Repositories Read. Enter as email:api_token.

Bitbucket: "Browse" doesn't show my repositories

Repository Access Tokens are scoped to a single repository and cannot list all repositories. Use "Add by URL" instead. To browse all repositories, you need a user-level API Token with scopes.

Scheduled job didn't run at the expected time

Scheduled triggers are checked hourly by the Atlassian platform. Your job will run within approximately 1 hour after the configured time. This is a platform-level constraint. If the job didn't run at all after 2+ hours, check:

• The job trigger is set to Scheduled (not Manual).
• The next scheduled run time shown in Queue & History → Upcoming Scheduled Jobs is correct.
• Your AI provider key and Git token are still valid.

Generated documentation is too short / missing sections

• Increase the output token limit in the job's Advanced AI Settings. Comprehensive presets need more tokens than Quick Reference.
• Include more relevant files — the AI can only document code it receives.
• Try a more capable AI model (larger models produce more detailed output).

Generated documentation contains inaccurate information

AI-generated documentation may contain errors or hallucinations. Always review generated content before sharing it. Tips:

• Use the Developer Documentation or Comprehensive Technical preset for the most accurate technical output.
• Include relevant files (config files, README, package.json) to give the AI more context.
• Use a more capable model for critical documentation.

17. FAQ

How much does AI usage cost?

CodeDoc AI itself charges no per-generation fee — you pay only for the Marketplace subscription (free or paid plan). AI costs are billed directly by your AI provider based on token usage. Each generation's token count is tracked in the history so you can monitor costs. A typical documentation generation for a medium repository uses 10,000–50,000 input tokens and 2,000–8,000 output tokens.

Can I use different AI models for different jobs?

Currently, one model is selected globally and used for all jobs. You can change the model at any time in Settings. If you need different models, run the first job, switch models in Settings, then run the second job.

Can I document multiple repositories in one job?

Yes. Each job can include up to 2 repositories. The AI receives code from all selected repositories and generates a single unified documentation page.

What programming languages and file types are supported?

CodeDoc AI shows all text-based files from your repository — there is no language whitelist. The file tree displays everything that is not explicitly excluded. The following are automatically filtered out, as they are not useful for documentation:

• Dependency directories: node_modules/, vendor/, .git/
• Build outputs: dist/, build/, .next/, target/, __pycache__/ etc.
• Lock files: package-lock.json, yarn.lock, Cargo.lock, go.sum etc.
• Binary & media files: images, fonts, archives, compiled binaries (.pyc, .class, .dll etc.)
• Environment files: .env, .env.local, .env.production etc.
• Certificates & keys: .pem, .key, .crt etc.

Everything else — JavaScript, TypeScript, Python, Java, C#, Go, Rust, Ruby, PHP, Swift, Kotlin, Dart, Vue, Svelte, HTML, CSS, SCSS, XML, Groovy, Solidity, R, Lua, shell scripts, Terraform, Protobuf, GraphQL, Dockerfiles, and more — is shown and can be selected. The AI model determines how well it understands each file type; popular languages and frameworks work best.

What languages can the documentation be generated in?

English, German, French, Spanish, Italian, Portuguese, Japanese, Chinese, and Korean are built in. You can also select "Custom" and specify any language — the AI will attempt to generate documentation in that language (quality depends on the AI model's capabilities).

Where is my documentation stored?

Documentation is published as a regular Confluence page in the space you selected. You can edit, move, or delete it like any other Confluence page. Running the job again will update the existing page (not create a duplicate). If the approval workflow is enabled, the page is created with a [DRAFT] prefix and remains visible in your space until you publish or discard it.

Can I review documentation before it goes live?

Yes. Enable "Require approval before publishing" in the job settings. The generated page will be saved as a draft with a [DRAFT] prefix. You can view, edit, and approve it from the Dashboard or Jobs tab before it becomes a regular published page. See Approval Workflow for details.

Do webhook and schedule triggers re-generate from scratch?

Yes. Each trigger causes a full regeneration — the app re-reads the current code from Git, sends it to the AI, and updates the Confluence page with fresh documentation.

Can I use the app with private repositories?

Yes. The app uses your personal access token to authenticate with your Git provider. As long as your token has read access to the repository, it works with both public and private repos.

How do I uninstall?

Go to Confluence Settings → Apps → Manage apps, find CodeDoc AI, and click Uninstall. This removes all app configuration and stored data. Generated Confluence pages remain in your spaces — delete them manually if needed.

18. Support