> ## Documentation Index
> Fetch the complete documentation index at: https://docs.factory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Automated Documentation

> Automatically update documentation when code changes using CI/CD workflows

This cookbook demonstrates how to use Droid Exec in GitHub Actions to automatically update documentation when code is merged to main. The workflow analyzes code changes, discovers relevant documentation, updates it, and creates a pull request for human review.

## How it works

End-to-end automated workflow:

1. **Trigger**: Code merged to main branch
2. **Explore**: Droid exec explores codebase structure (project type, tech stack)
3. **Analyze**: Identifies changed files and their purpose
4. **Discover**: Searches docs/ directory for relevant documentation
5. **Update**: Updates affected documentation sections
6. **Commit**: Workflow creates commit
7. **PR**: Bot opens pull request for team review

## Prerequisites

To get started, you'll need:

* Droid installed
* A Factory API key
* GitHub repository with Actions enabled
* `FACTORY_API_KEY` in repository secrets (Settings → Secrets → Actions)
* Existing documentation directory

<Note>
  See the Droid Exec setup [here](/cli/droid-exec/overview#installation).
</Note>

## Complete GitHub Actions workflow

<Info>
  This workflow will create pull requests automatically. Review the generated PRs carefully before merging to ensure accuracy.
</Info>

Create `.github/workflows/update-docs.yml`:

```yaml theme={null}
name: Auto-Update Documentation

on:
  push:
    branches: [main]
    paths:
      - 'src/**/*.ts'
      - 'src/**/*.tsx'
      - 'src/**/*.js'
      - 'src/**/*.py'

jobs:
  update-docs:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}
      
      - name: Setup droid CLI
        run: |
          curl -fsSL https://app.factory.ai/cli | sh
          echo "$HOME/.local/bin" >> $GITHUB_PATH
      
      - name: Get changed files
        id: changes
        run: |
          git diff --name-only HEAD^ HEAD > changed_files.txt
          echo "Files changed in last commit:"
          cat changed_files.txt
      
      - name: Update documentation
        env:
          FACTORY_API_KEY: ${{ secrets.FACTORY_API_KEY }}
        run: |
          droid exec --auto low "
          The following source files were just merged to main:
          $(cat changed_files.txt)
          
          Your task is to update the documentation to match these code changes.
          
          First, explore the codebase to understand context:
          1. Examine package.json, README, and main entry points
          2. Identify key directories and their purposes
          3. Note the tech stack (languages, frameworks, tools)
          4. Classify the project type:
             - **Library/SDK**: Exports functions/classes, has API docs, used as dependency
             - **Application**: Has routes/pages, domain models, user features
             - **Framework/Protocol**: Defines specs, client/server implementations
             - **Monorepo**: Multiple packages/apps in one repository
          
          Then, understand what changed:
          1. Read each changed file carefully
          2. Identify if changes are: API updates, new features, bug fixes, refactors
          3. Note breaking changes or new configuration options
          
          Next, find and update relevant documentation:
          1. Search the docs/ directory for files that reference:
             - The changed filenames or paths
             - Functions, classes, or APIs that were modified
             - Features or concepts affected by the changes
          2. Update the found documentation:
             - Update function signatures if they changed
             - Update code examples to match new APIs
             - Update configuration docs if options changed
             - Update explanations if behavior changed
             - Add notes about breaking changes if needed
          3. Preserve the existing doc structure and writing style
          4. Only modify sections that are actually affected
          
          DO NOT commit or push changes.
          
          Finally, create doc-update-summary.md with:
          - List of documentation files that were updated
          - Summary of changes made to each file
          - Any sections that may need human review or clarification
          "
      
      - name: Commit documentation updates
        run: |
          if [ -n "$(git status --porcelain)" ]; then
            git config user.name "github-actions[bot]"
            git config user.email "github-actions[bot]@users.noreply.github.com"
            git add -A
            git commit -m "docs: automated documentation updates"
          else
            echo "No documentation changes needed"
            exit 0
          fi
      
      - name: Create Pull Request
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          BRANCH="docs/auto-update-$(date +%Y%m%d-%H%M%S)"
          git checkout -b $BRANCH
          git push origin $BRANCH
          
          # Get summary or use default message
          SUMMARY=$(cat doc-update-summary.md 2>/dev/null || echo "Documentation updated to reflect recent code changes.")
          
          gh pr create \
            --title "📚 Automated documentation updates" \
            --body "## Automated Documentation Updates

$SUMMARY

### Review Checklist
- [ ] Documentation accurately reflects code changes
- [ ] Code examples are correct and runnable
- [ ] No unintended changes to other sections
- [ ] Formatting and style are consistent

---
This PR was automatically generated after code was merged to main." \
            --label "documentation,automated"
```

**Key workflow features:**

* Uses `--auto low` for file modifications only (following cookbook patterns)
* Explicit instruction: "DO NOT commit or push" (separation of concerns)
* Workflow handles git operations in separate step
* Droid autonomously explores codebase and discovers relevant docs (no mapping file needed)

## Best practices

<Steps>
  <Step title="Scope triggers carefully">
    Only trigger on meaningful code changes:

    ```yaml theme={null}
    paths:
      - 'src/**'
      - '!src/**/*.test.ts'
      - '!src/**/*.spec.ts'
    ```
  </Step>

  <Step title="Use --auto low for safety">
    Following cookbook patterns:

    ```bash theme={null}
    droid exec --auto low "..." # File changes only
    # Workflow handles git operations separately
    ```
  </Step>

  <Step title="Trust autonomous discovery">
    Let droid explore and find relevant docs rather than maintaining manual mappings:

    ```bash theme={null}
    "Search the docs/ directory for files that reference the changed code"
    ```
  </Step>

  <Step title="Always generate summaries">
    Help reviewers understand changes:

    ```bash theme={null}
    "Create doc-update-summary.md explaining what was updated and why"
    ```
  </Step>

  <Step title="Consider rate limits">
    For high-frequency repos, use scheduled batch updates:

    ```yaml theme={null}
    schedule:
      - cron: '0 9 * * 1'  # Weekly on Monday
    ```
  </Step>
</Steps>

## Variations

### Weekly comprehensive review

For repositories with frequent changes, batch updates into a weekly review:

```yaml theme={null}
on:
  schedule:
    - cron: '0 9 * * 1'  # Monday 9 AM
  workflow_dispatch:  # Allow manual trigger
```

### Multiple documentation directories

If your docs are spread across multiple locations:

```bash theme={null}
droid exec --auto low "
Search docs/, guides/, and README.md for documentation to update
based on these code changes: $(cat changed_files.txt)
"
```

### Language-specific targeting

Focus on specific file types:

```yaml theme={null}
on:
  push:
    branches: [main]
    paths:
      - 'src/**/*.ts'
      - 'src/**/*.tsx'
      # TypeScript changes only
```

## Troubleshooting

<Accordion title="No PR created even though code changed">
  Droid may have determined no docs needed updates. Check the workflow logs or add more specific search instructions in the prompt. You can also check if `doc-update-summary.md` was created to see what droid analyzed.
</Accordion>

<Accordion title="Wrong sections get updated">
  Improve the exploration prompt to be more specific about what to look for. Consider adding explicit instructions about which doc sections should or shouldn't be modified.
</Accordion>

<Accordion title="Droid can't find relevant docs">
  Make the search instructions more explicit by pointing Droid Exec at specific directories, filenames, or keywords. Providing a short list of likely docs can dramatically improve accuracy.
</Accordion>

<Accordion title="Workflow times out">
  For large repositories, consider:

  * Increasing the timeout in the workflow
  * Processing documentation updates in batches
  * Using scheduled updates instead of triggering on every merge
</Accordion>

## See also

* [Droid Exec Overview](/cli/droid-exec/overview) - Autonomy levels and capabilities
* [GitHub Actions Cookbook](/guides/droid-exec/github-actions) - More workflow examples
* [Documentation Sync Hooks](/guides/hooks/documentation-sync) - Preventive approach