Documentation & Changelog Automation

Documentation automation uses Codex to keep docs in sync with code changes. When a PR modifies a public API, Codex generates updated JSDoc comments, API reference entries, and changelog items. When a PR adds a new feature, Codex drafts a user-facing documentation section. The automation catches the most common documentation failure: code changes without corresponding doc updates, which cause docs to drift from reality.

Changelog generation is the simplest and most impactful documentation automation. Codex reads the PR diff and commit messages, categorizes changes (feature, fix, breaking change, internal), and generates a CHANGELOG.md entry in Keep a Changelog format. The generated entry is posted as a PR comment for the author to review and include. This turns changelog maintenance from a forgotten chore into a reviewed artifact.

name: Codex Documentation
on:
  pull_request:
    types: [opened, synchronize]
    paths:
      - 'src/**/*.ts'
      - 'src/**/*.tsx'

jobs:
  doc-check:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @openai/codex
      - name: Generate changelog entry
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          DIFF=$(git log --oneline origin/${{ github.base_ref }}..HEAD)
          codex --profile ci --approval full-auto \
            "Based on these commits, generate a CHANGELOG.md entry
             in Keep a Changelog format. Categorize as:
             Added, Changed, Fixed, Removed, Security.
             Be concise. One line per change." \
            < <(echo "$DIFF") > changelog-entry.md
      - name: Post as PR comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const entry = fs.readFileSync('changelog-entry.md', 'utf8');
            await github.rest.issues.createComment({
              ...context.repo,
              issue_number: context.payload.pull_request.number,
              body: `## Suggested Changelog Entry\n\n${entry}\n\n*Generated by Codex*`,
            });