agent-governance-toolkit/.github/workflows/ai-docs-sync.yml at cb7b16770c96b4db13cf08afe9a5596c5cc90386 · imran-siddique/agent-governance-toolkit · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
# AI-powered documentation freshness check for agent-governance-toolkit.
# When a PR touches package source code, verifies that corresponding
# documentation is updated — flags missing docstrings, stale READMEs,
# and changed behavior without CHANGELOG entries.
name: AI Docs Sync Check

on:
  pull_request_target:
    types: [opened, synchronize, reopened]
    branches: [main]
    paths:
      - "packages/*/src/**"

permissions:
  contents: read
  pull-requests: write
  models: read

jobs:
  docs-freshness:
    name: Documentation Freshness Check
    runs-on: ubuntu-latest
    if: >-
      github.event.pull_request.draft == false &&
      github.actor != 'dependabot[bot]'
    continue-on-error: true
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          # SECURITY: pull_request_target — checkout base branch (default), NOT
          # the PR head. The composite action fetches the diff via GitHub API,
          # so checking out HEAD is unnecessary and would let a malicious PR
          # modify .github/actions/ code that runs with elevated GITHUB_TOKEN.
          fetch-depth: 0

      - name: Check documentation freshness
        uses: ./.github/actions/ai-agent-runner
        with:
          agent-type: docs-sync-checker
          github-token: ${{ secrets.GITHUB_TOKEN }}
          model: gpt-4o
          fallback-model: gpt-4o-mini
          max-tokens: "4000"
          context-mode: pr-diff
          output-mode: pr-comment
          custom-instructions: |
            You are a documentation freshness checker for microsoft/agent-governance-toolkit.

            Analyze the PR diff and check:
            1. **New public APIs without docstrings** — all public functions, classes, and
               methods should have docstrings explaining purpose, parameters, return values,
               and exceptions
            2. **README sections out of date** — if behavior changes, does the package README
               reflect it?
            3. **CHANGELOG missing entries** — behavioral changes should have a CHANGELOG.md entry
            4. **Example code outdated** — if API signatures change, examples/ should be updated
            5. **Type hints** — new public APIs should have complete type annotations

            Monorepo structure:
            - packages/{name}/src/ — source code
            - packages/{name}/README.md — package documentation
            - packages/{name}/tests/ — test files
            - docs/ — project-level documentation
            - CHANGELOG.md — project changelog

            Format:
            ## 📝 Documentation Sync Report

            ### Issues Found
            - ❌ `function_name()` in `package/module.py` — missing docstring
            - ⚠️ `package/README.md` — section X may need update for new behavior
            - ⚠️ CHANGELOG.md — no entry for this change

            ### Suggestions
            - 💡 Add docstring for `function_name(param1: str, param2: int) -> bool`
            - 💡 Update README section "Configuration" to mention new option

            If everything looks good, say ✅ Documentation is in sync.