Skip to main content

Auto-Doc Pipeline Configuration

Overview​

The auto-doc/* pipeline is designed to automatically generate documentation using Claude Code and deploy preview sites. It includes safeguards to prevent re-generation of content when technical writers make manual edits.

Pipeline Flow​

When you push to an auto-doc/* branch, the pipeline executes two steps:

Step 1: Generate Documentation with Claude Code​

  1. Skip Check: Verifies if Claude has already generated documentation for this branch
  2. Claude Generation: Runs Claude Code to generate documentation from JIRA issue
  3. Commit: Commits generated documentation with [skip ci] tag
  4. Artifacts: Captures generated markdown files and debug logs

Step 2: Build Preview and Post Link to PR​

  1. Linting: Runs markdown linting and spell checking
  2. Build: Builds the Docusaurus site
  3. Deploy: Deploys to Firebase preview channel (expires in 7 days)
  4. PR Comment: Posts preview link as a comment on the pull request

One-Time Generation Guarantee​

The pipeline ensures Claude generates documentation only once per branch:

How It Works​

  1. First Push: Claude generates documentation and commits with Co-Authored-By: Claude
  2. Subsequent Pushes: Pipeline detects existing Claude commit and skips generation
  3. Manual Edits: Tech writers can freely edit generated files without triggering re-generation

Skip Logic​

The pipeline checks for Claude commits only in the current branch since it diverged from trunk:

# Get the merge base (where this branch diverged from trunk)
MERGE_BASE=$(git merge-base HEAD origin/trunk)

# Only check commits that are unique to this branch (not in trunk)
CLAUDE_COMMITS=$(git log $MERGE_BASE..HEAD --grep="Co-Authored-By: Claude" --oneline | grep -c "^")

if [ "$CLAUDE_COMMITS" -gt "0" ]; then
  echo "🤖 Claude has already generated documentation for this branch"
  echo "⏭️  Skipping auto-doc pipeline to prevent re-generation"
  exit 0
fi

Why this approach? When JIRA creates a new auto-doc/* branch from trunk, the branch contains all of trunk's history, including previous Claude commits. By using git merge-base, we only check commits that were added after the branch was created, not the entire git history.

When Claude Runs​

✅ Will Generate:

  • First push to a new auto-doc/* branch
  • No existing commits authored by Claude

❌ Will Skip:

  • Any push after Claude has generated documentation
  • Commits with [skip ci] in the message
  • Manual edits by tech writers
  • Fixes to linting issues

Preview Deployment​

Preview URL Format​

https://public-documentation-8353f--docs-preview-{unique-id}.web.app

Preview Features​

  • Expiry: 7 days (configurable via --expires flag)
  • Channel: docs-preview (shared across all PRs)
  • Access: Public URL, no authentication required

Finding Your Preview URL​

  1. Bitbucket Pipeline: Check the "Build Preview and Post Link to PR" step output
  2. PR Comment: The pipeline automatically posts the preview link as a comment
  3. Firebase Console: View all preview channels at https://console.firebase.google.com

PR Comment​

When the preview is ready, the pipeline posts a comment to the pull request:

## 🤖 Claude Documentation Preview Ready

Your AI-generated documentation is now available for review:

### 📍 Preview Link
[View Documentation Preview](https://public-documentation-8353f--docs-preview-xxx.web.app)

### 📋 Issue Details

- Issue Key: PLAYG-123
- Branch: auto-doc/PLAYG-123
- Pipeline: {pipeline-uuid}

### ⏰ Preview Expiry
This preview will expire in 7 days.

### ✅ Next Steps

1. Review the generated documentation
2. Make any necessary edits
3. Commit your changes (Claude will not re-generate)
4. Merge the PR when ready

Environment Variables Required​

For Claude Generation​

  • ANTHROPIC_API_KEY: Claude API key
  • ATLASSIAN_USERNAME: JIRA username
  • ATLASSIAN_API_TOKEN: JIRA API token
  • ATLASSIAN_INSTANCE_URL: JIRA instance URL

For Preview Deployment​

  • FIREBASE_SERVICE_ACCOUNT_ENCODED: Base64-encoded Firebase service account JSON
  • BITBUCKET_PR_ID: PR ID (automatically set by Bitbucket)
  • BITBUCKET_REPO_SLUG: Repository slug (automatically set)
  • BITBUCKET_WORKSPACE: Workspace slug (automatically set)

For PR Comments​

  • BITBUCKET_ACCESS_TOKEN: Access token for Bitbucket API (optional)
    • If not set, preview URL will be logged but not posted to PR
    • Add this token to repository variables to enable PR comments

Manual Override​

If you need to regenerate documentation (e.g., Claude made an error):

Option 1: Force New Generation​

  1. Delete the branch and create a new auto-doc/* branch
  2. This resets the Claude commit history check

Option 2: Manual Commit Edit​

  1. Rewrite git history to remove Claude's commit (use with caution)
  2. Force push to the branch
# Find Claude's commit
git log --grep="Co-Authored-By: Claude"

# Reset to before Claude's commit (replace <commit-hash>)
git reset --hard <commit-hash>

# Force push
git push --force origin auto-doc/PLAYG-XXX

⚠️ Warning: Force pushing can cause issues if others have pulled the branch.

Troubleshooting​

Pipeline Skips Generation Unexpectedly​

Problem: Pipeline says "Claude has already generated documentation" but you haven't seen any commits.

Possible Causes:

  1. Trunk was not fetched: Pipeline couldn't find the merge base with trunk
  2. Branch has Claude commits: There are actual Claude commits on the branch

Solution:

Check if there are Claude commits on your branch (not in trunk):

# Get merge base
MERGE_BASE=$(git merge-base HEAD origin/trunk)

# Check Claude commits since branching
git log $MERGE_BASE..HEAD --grep="Co-Authored-By: Claude" --oneline

If this shows commits, Claude has already run. If empty, the pipeline should have allowed generation.

Problem: Preview deploys successfully but no comment appears on PR.

Possible Causes:

  1. BITBUCKET_ACCESS_TOKEN not set
  2. BITBUCKET_PR_ID not available (branch not in a PR)
  3. Insufficient permissions for the access token

Solution:

  • Check repository variables for BITBUCKET_ACCESS_TOKEN
  • Ensure the branch is in an open pull request
  • Verify token has pullrequest:write permission

Preview URL Shows 404​

Problem: Preview URL is generated but shows "Page Not Found".

Possible Causes:

  1. Build failed but deployment succeeded
  2. Page path doesn't match URL structure
  3. Sidebar configuration missing the page

Solution:

  • Check the build logs for errors
  • Verify front matter in the markdown file
  • Test the build locally: npm run build && npm run serve

Workflow Example​

Typical Auto-Doc Flow​


1. Create JIRA issue (PLAYG-123)

   └─> Title: "Add 2FA Documentation"

2. Create branch: auto-doc/PLAYG-123

   └─> Push to remote

3. Pipeline Step 1: Claude Generation

   ├─> Claude reads JIRA issue
   ├─> Claude generates markdown documentation
   ├─> Claude commits with [skip ci]
   └─> Artifacts: solutions/**/*.md

4. Pipeline Step 2: Preview Deployment

   ├─> Lint markdown files
   ├─> Build Docusaurus site
   ├─> Deploy to Firebase preview
   ├─> Post preview link to PR
   └─> Output: https://...--docs-preview-xxx.web.app

5. Tech Writer Review

   ├─> Review preview site
   ├─> Make manual edits if needed
   ├─> Commit changes
   └─> Pipeline skips Claude generation (already run)

6. Merge PR

   └─> Documentation merged to trunk

Best Practices​

For Developers​

  1. Branch Naming: Always use auto-doc/JIRA-KEY format
  2. JIRA Issues: Ensure issue has clear description before creating branch
  3. Review Previews: Check preview site before merging

For Tech Writers​

  1. Edit Freely: Make changes directly to generated markdown
  2. No Re-generation: Your edits won't be overwritten by Claude
  3. Commit Often: Regular commits help track changes

For DevOps​

  1. Token Rotation: Rotate BITBUCKET_ACCESS_TOKEN periodically
  2. Firebase Cleanup: Old preview channels auto-expire after 7 days
  3. Monitor Logs: Check pipeline logs for generation errors
  • scripts/claude-documentation-automation.js: Main Claude automation script
  • scripts/post-preview-comment.js: Posts preview link to PR
  • scripts/deploy-preview.js: Sets up preview environment
  • scripts/fix-markdown-linting.js: Auto-fixes markdown linting issues

See Also​

  • Local Verification Guide: Guide for running pipeline checks locally
  • Repository Overview: See CLAUDE.md in the repository root for Claude Code instructions
  • Pipeline Configuration: See bitbucket-pipelines.yml in the repository root