Quick start

CodeDoc for Confluence, connected in about 5 minutes.

Before you start: you need an access token from your Git hosting service with read access. That is all sync blocks need. AI pages are optional. When a Confluence admin opens CodeDoc for the first time, a short setup assistant walks through both.
On this page
  1. Connect your Git provider
  2. Add your first sync block
  3. AI pages (optional)
  4. Access control · What's next

1. Connect your Git provider

CodeDoc only reads files; it never writes to your repositories. The token is stored encrypted in your Confluence site (Forge secret storage) and is never shown again. Open the steps for your provider:

GitHub: fine-grained access token
  1. Go to github.com/settings/personal-access-tokens/new.
  2. Give the token a name (e.g. "CodeDoc") and an expiration date.
  3. Under Repository access, choose the repositories CodeDoc should read.
  4. Under Repository permissions, set Contents to Read-only.
  5. Click Generate token and copy it; it starts with github_pat_ and is shown only once.
  6. In CodeDoc, choose GitHub, paste the token into Access token and click Connect and continue (in Settings later: Connect). CodeDoc confirms the account it is connected as.

A classic token (ghp_) with the repo scope works too. If the repositories belong to an organization, the organization may have to approve a fine-grained token first.

GitLab: personal access token
  1. Go to gitlab.com/-/user_settings/personal_access_tokens and click Add new token.
  2. Select the scopes read_api and read_repository.
  3. Click Create personal access token and copy it; it starts with glpat- and is shown only once.
  4. In CodeDoc, choose GitLab, paste the token and click Connect and continue.

Group and project access tokens with the same scopes work too, and subgroups (group/subgroup/project) are supported. Your own GitLab server: see Own server.

Bitbucket Cloud: access token

Repository access token (one repository, all plans):

  1. Open the repository in Bitbucket → Repository settings → Access tokens.
  2. Create a token with the permission Repositories: Read and copy it.
  3. In CodeDoc, choose Bitbucket Cloud, paste the token and click Connect and continue.
  4. Add the repository in Repositories → Add by address (paste its address).

Project or workspace access token (several repositories, Bitbucket Premium): create it in the project or workspace settings → Access tokens with Repositories: Read, paste it the same way and add each repository with Add by address. Bitbucket does not let access tokens list repositories, so Browse repositories is not available for Bitbucket; CodeDoc checks the token when you add a repository.

No personal API tokens: Atlassian's security requirements do not allow Marketplace apps to collect or store the credentials of Atlassian accounts, so CodeDoc does not accept personal Bitbucket API tokens or app passwords. A repository access token reads only its own repository: add one connection per repository, or use a project or workspace token.
Azure DevOps: personal access token
  1. Go to dev.azure.com, open your organization, then User settings (top right) → Personal access tokens.
  2. Click + New Token, give it a name and set the scope Code to Read.
  3. Click Create and copy the token; it is shown only once.
  4. In CodeDoc, choose Azure DevOps, paste the token, enter your Organization URL (https://dev.azure.com/your-org) and click Connect and continue.

The organization URL is required. You find it in your browser's address bar when you are signed in to Azure DevOps, e.g. https://dev.azure.com/mycompany.

GitHub Enterprise or GitLab self-managed: your own server
  1. In CodeDoc, choose GitHub Enterprise (own server or ghe.com) or GitLab self-managed and enter the address you open the server with, e.g. https://github.example.com or https://example.com/gitlab.
  2. Click Allow access to the server. Atlassian asks a site admin to confirm that CodeDoc may send requests to this address.
  3. Create a read-only token on your server (GitHub Enterprise: Contents read-only, or a classic token with repo; GitLab: read_api and read_repository), paste it and click Connect and continue. Right after a new approval, Atlassian needs a short while; CodeDoc tries again by itself.
Reachable from Atlassian's cloud: CodeDoc runs on Atlassian Forge, not in your network. The server must be reachable over HTTPS with a certificate from a public certificate authority. Behind a firewall, allow Atlassian's outgoing IP addresses. Admins see and can remove the approval in Atlassian Administration → Connected apps → CodeDoc → Data management.

2. Add your first sync block

A sync block shows a value, a section or code from a file on a Confluence page and keeps it up to date. It needs no AI and causes no token costs.

  1. In CodeDoc, open Repositories and add the repository: Browse repositories or Add by address.
  2. Edit a Confluence page, type / and choose CodeDoc Sync Block.
  3. Paste the link to a file, for example https://github.com/helm/examples/blob/main/charts/hello-world/Chart.yaml, and click Use link. Or pick the repository and the file.
  4. Choose what to show: values (pick the keys from a list), a Markdown section, the latest changelog entry, a snippet between markers, some lines or the whole file.
  5. Choose when it updates (on every push, daily, weekly or only by hand), check the preview, save and publish the page.

The content is normal page text, so Confluence search, export and page history include it. All details: Sync blocks. To update on every push, add the CodeDoc webhook to the repository.

3. AI pages (optional)

CodeDoc Advanced includes Atlassian AI, so there is nothing to connect: click Continue with Atlassian AI in the setup assistant (how the allowance works).

With the Standard edition, or if you prefer your own model and contract, connect your own AI provider. CodeDoc calls it directly with your key, so your own contract and billing apply. You can skip this step and connect a provider later in Settings → Connections.

Anthropic (Claude)
  1. Go to platform.claude.com/settings/keys, click Create Key and copy the key.
  2. In CodeDoc, choose Anthropic, paste the key into API key and click Connect and continue.
  3. Choose a model: recommended models come first; type to search all models of your account.

Anthropic needs a payment method even for low usage: platform.claude.com/settings/billing.

OpenAI (GPT)
  1. Go to platform.openai.com/api-keys, click + Create new secret key and copy it (shown only once).
  2. In CodeDoc, choose OpenAI, paste the key and click Connect and continue, then choose a model.

Make sure your account has credits: platform.openai.com/settings/organization/billing.

Google (Gemini)
  1. Go to aistudio.google.com/app/apikey, click Create API key and choose or create a Google Cloud project.
  2. In CodeDoc, choose Google AI (Gemini), paste the key and click Connect and continue, then choose a model.

Google's free tier with rate limits is good for a first test. On the free tier Google may use what you send to improve its products, so use it only with code you are allowed to share that way; a key with billing enabled avoids this.

Costs depend on the model and how many files you choose; smaller models (Claude Haiku, GPT mini, Gemini Flash) cost a fraction of the large ones. Set a spending limit in your provider account. Sync blocks never call an AI provider.

Access control (optional)

By default, only Confluence administrators can use CodeDoc. To give others access, open Settings → Permissions and add Confluence groups to one of two roles:

  • Administrator: everything, including connections, repositories, Settings and Permissions.
  • Job Operator: sets up sync blocks and creates and runs AI pages, but cannot change Settings or Permissions.

Manage the members of these groups in Confluence (Confluence administration → Groups); nothing changes in the app when people join or leave. Tip: a group like codedoc-ai-operators for the Job Operator role. Sync blocks on a page are visible to everyone who can see the page.

What's next

  • Overview shows your sync blocks and AI pages at a glance and what needs attention.
  • Sync blocks lists every block with its page, source and status; Update now refreshes one.
  • AI pages → New AI page walks you through four steps: source files, content (writing style, language), target page and when the page updates.
  • Settings → Webhook sets up updates on every push (create the webhook secret there first).

All details are in the documentation. Questions: support@janekbehrens.de.

Documentation · Support · Privacy Policy · Impressum