Documentation bot

[peholmst]

Documentation Bot

An agentic GitHub workflow that automatically creates documentation PRs in vaadin/docs when code changes affect user-facing features, APIs, or behavior.

Powered by GitHub Agentic Workflows (gh-aw) and Claude.

How It Works

1. A developer opens or updates a PR in a source repository.
2. The bot analyzes the PR diff and classifies changes (new features, API changes, deprecations, etc.).
3. If documentation updates are needed, the bot creates a draft PR in vaadin/docs with the relevant changes.
4. The draft PR is assigned to the original PR author for review.
5. A comment is posted on the source PR linking to the docs PR.

If no documentation changes are needed (internal/test/build-only changes), the bot comments accordingly and takes no further action.

Prerequisites

• GitHub CLI (gh) installed and authenticated
• The gh-aw extension: gh extension install github/gh-aw

Installation

1. Copy the workflow file

Copy .github/workflows/doc-bot.md from this repository into the target repository:

# From the target repository root
mkdir -p .github/workflows
cp /path/to/github-doc-bot/.github/workflows/doc-bot.md .github/workflows/

2. Compile the workflow

gh aw compile

This produces .github/workflows/doc-bot.lock.yml — the compiled GitHub Actions workflow.

3. Set secrets

The workflow requires two secrets:

Secret	Purpose	How to obtain
ANTHROPIC_API_KEY	Claude AI engine for the agentic workflow	Create at console.anthropic.com
DOCS_REPO_TOKEN	Read/write access to vaadin/docs	GitHub Fine-grained PAT (see below)

gh aw secrets set ANTHROPIC_API_KEY
gh aw secrets set DOCS_REPO_TOKEN

Creating the DOCS_REPO_TOKEN

Create a Fine-grained Personal Access Token with:

• Repository access: vaadin/docs only
• Permissions:
  • Contents: Read and write
  • Pull requests: Read and write
  • Issues: Read and write
  • Metadata: Read-only

4. Commit and push

git add .github/workflows/doc-bot.md .github/workflows/doc-bot.lock.yml
git commit -m "Add documentation bot workflow"
git push

5. Test

Open a PR with a user-facing change (e.g., adding a new public API method) and check the Actions tab. You should see:

• The workflow triggers on the PR
• A draft PR appears in vaadin/docs assigned to the PR author
• A comment on the source PR links to the docs PR

Also test with an internal-only change to verify the bot correctly skips documentation.

Organization-Wide Deployment

To deploy across multiple Vaadin repositories:

1. Set ANTHROPIC_API_KEY and DOCS_REPO_TOKEN as organization secrets scoped to the relevant repositories.
2. Copy doc-bot.md and run gh aw compile in each repository, then commit both files.

Configuration

The workflow is configured in the frontmatter of doc-bot.md. Key settings:

Setting	Default	Description
timeout-minutes	30	Maximum runtime for the workflow
draft	true	Docs PRs are created as drafts
expires	14	Auto-close stale docs PRs after 14 days
fallback-as-issue	true	If PR creation fails, create an issue instead
base-branch	main	Target branch in vaadin/docs

Troubleshooting

Workflow doesn't trigger

• Ensure the compiled .lock.yml file is committed alongside the .md file.
• Check that both secrets are set: gh aw secrets list.

PR creation fails

• Verify the DOCS_REPO_TOKEN has write access to vaadin/docs.
• Check the Actions log for detailed error messages.
• If PR creation fails, the bot falls back to creating an issue in vaadin/docs.

Duplicate docs PRs

• On synchronize events (PR updates), the bot searches for existing docs PRs before creating new ones. If duplicates appear, check that the branch naming pattern (doc-bot/<repo>/<pr-number>) is consistent.

[sonarqubecloud]

Quality Gate passed

Issues
79 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

Test Results

 1 360 files  ±0   1 360 suites  ±0   1h 20m 44s ⏱️ - 2m 54s
 9 659 tests ±0   9 592 ✅ ±0  67 💤 ±0  0 ❌ ±0 
10 118 runs   - 1  10 045 ✅ +2  73 💤  - 3  0 ❌ ±0 

Results for commit 0a86ef4. ± Comparison against base commit fec80a7.