ci(docs): Add agentic workflows for codebase documentation#5649
Merged
ci(docs): Add agentic workflows for codebase documentation#5649
Conversation
Add GitHub Agentic Workflows that auto-generate and maintain developer-facing codebase documentation in docs/codebase/. Two workflows: full refresh (on merge + manual) and incremental update (on merge, path-filtered to sentry_sdk/**). Designed to be portable across Sentry SDKs -- only the SDK Context block in each workflow changes per language. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
Semver Impact of This PR🟢 Patch (bug fixes) 📋 Changelog PreviewThis is how your changes will appear in the changelog. New Features ✨Pydantic Ai
Other
Bug Fixes 🐛
Documentation 📚
Internal Changes 🔧Openai Agents
Other
🤖 This preview updates automatically when you update the PR. |
Contributor
Codecov Results 📊✅ 13 passed | Total: 13 | Pass Rate: 100% | Execution Time: 15.11s All tests are passing successfully. ✅ Patch coverage is 100.00%. Project has 14064 uncovered lines. Generated by Codecov Action |
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 2 potential issues.
Autofix Details
Bugbot Autofix prepared fixes for both issues found in the latest run.
- ✅ Fixed: Refresh workflow fires on every push, duplicating update workflow
- I removed the
pushtrigger fromdocs-codebase-refreshso full refresh now runs only viaworkflow_dispatchand no longer competes with incremental updates.
- I removed the
- ✅ Fixed: Incremental update uses HEAD~1, misses multi-commit pushes
- I updated the incremental workflow instructions to diff
github.event.beforetogithub.sha, which captures all commits included in the push.
- I updated the incremental workflow instructions to diff
Or push these changes by commenting:
@cursor push a844745d91
Preview (a844745d91)
diff --git a/.github/workflows/docs-codebase-refresh.lock.yml b/.github/workflows/docs-codebase-refresh.lock.yml
--- a/.github/workflows/docs-codebase-refresh.lock.yml
+++ b/.github/workflows/docs-codebase-refresh.lock.yml
@@ -21,29 +21,23 @@
#
# For more information: https://github.github.com/gh-aw/introduction/overview/
#
-# Full refresh of SDK codebase documentation on merge or manual trigger
+# Full refresh of SDK codebase documentation on manual trigger
#
-# gh-aw-metadata: {"schema_version":"v2","frontmatter_hash":"4f4d3142638834f81965ef307bd7c5bf563be18193d3bb19d19f5dfb1e5e24f0","compiler_version":"v0.57.2","strict":true}
+# gh-aw-metadata: {"schema_version":"v2","frontmatter_hash":"4847b13b1721c3bc0b883e956accbbbe448e0d1f0b2471818a7523c0a0ea234e","compiler_version":"v0.57.2","strict":true}
name: "docs-codebase-refresh"
"on":
- push:
- branches:
- - main
- - master
workflow_dispatch:
permissions: {}
concurrency:
- group: "gh-aw-${{ github.workflow }}-${{ github.ref || github.run_id }}"
+ group: "gh-aw-${{ github.workflow }}"
run-name: "docs-codebase-refresh"
jobs:
activation:
- needs: pre_activation
- if: needs.pre_activation.outputs.activated == 'true'
runs-on: ubuntu-slim
permissions:
contents: read
@@ -192,7 +186,6 @@
GH_AW_GITHUB_REPOSITORY: ${{ github.repository }}
GH_AW_GITHUB_RUN_ID: ${{ github.run_id }}
GH_AW_GITHUB_WORKSPACE: ${{ github.workspace }}
- GH_AW_NEEDS_PRE_ACTIVATION_OUTPUTS_ACTIVATED: ${{ needs.pre_activation.outputs.activated }}
with:
script: |
const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs');
@@ -211,8 +204,7 @@
GH_AW_GITHUB_EVENT_PULL_REQUEST_NUMBER: process.env.GH_AW_GITHUB_EVENT_PULL_REQUEST_NUMBER,
GH_AW_GITHUB_REPOSITORY: process.env.GH_AW_GITHUB_REPOSITORY,
GH_AW_GITHUB_RUN_ID: process.env.GH_AW_GITHUB_RUN_ID,
- GH_AW_GITHUB_WORKSPACE: process.env.GH_AW_GITHUB_WORKSPACE,
- GH_AW_NEEDS_PRE_ACTIVATION_OUTPUTS_ACTIVATED: process.env.GH_AW_NEEDS_PRE_ACTIVATION_OUTPUTS_ACTIVATED
+ GH_AW_GITHUB_WORKSPACE: process.env.GH_AW_GITHUB_WORKSPACE
}
});
- name: Validate prompt placeholders
@@ -927,7 +919,7 @@
uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
env:
WORKFLOW_NAME: "docs-codebase-refresh"
- WORKFLOW_DESCRIPTION: "Full refresh of SDK codebase documentation on merge or manual trigger"
+ WORKFLOW_DESCRIPTION: "Full refresh of SDK codebase documentation on manual trigger"
HAS_PATCH: ${{ steps.collect_output.outputs.has_patch }}
with:
script: |
@@ -1134,29 +1126,6 @@
const { main } = require('/opt/gh-aw/actions/handle_create_pr_error.cjs');
await main();
- pre_activation:
- runs-on: ubuntu-slim
- outputs:
- activated: ${{ steps.check_membership.outputs.is_team_member == 'true' }}
- matched_command: ''
- steps:
- - name: Setup Scripts
- uses: github/gh-aw/actions/setup@32b3a711a9ee97d38e3989c90af0385aff0066a7 # v0.57.2
- with:
- destination: /opt/gh-aw/actions
- - name: Check team membership for workflow
- id: check_membership
- uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
- env:
- GH_AW_REQUIRED_ROLES: admin,maintainer,write
- with:
- github-token: ${{ secrets.GITHUB_TOKEN }}
- script: |
- const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs');
- setupGlobals(core, github, context, exec, io);
- const { main } = require('/opt/gh-aw/actions/check_membership.cjs');
- await main();
-
safe_outputs:
needs:
- activation
diff --git a/.github/workflows/docs-codebase-refresh.md b/.github/workflows/docs-codebase-refresh.md
--- a/.github/workflows/docs-codebase-refresh.md
+++ b/.github/workflows/docs-codebase-refresh.md
@@ -1,9 +1,7 @@
---
name: docs-codebase-refresh
-description: Full refresh of SDK codebase documentation on merge or manual trigger
+description: Full refresh of SDK codebase documentation on manual trigger
on:
- push:
- branches: [main, master]
workflow_dispatch:
permissions:
contents: read
diff --git a/.github/workflows/docs-codebase-update.md b/.github/workflows/docs-codebase-update.md
--- a/.github/workflows/docs-codebase-update.md
+++ b/.github/workflows/docs-codebase-update.md
@@ -41,8 +41,9 @@
### Step 1: Identify Changed Files
-Run `git diff HEAD~1 --name-only` to get the list of changed files in the
-latest commit. Filter to files matching the trigger paths:
+Run `git diff {{ github.event.before }} {{ github.sha }} --name-only` to get
+the list of changed files for the full push range. Filter to files matching
+the trigger paths:
- `sentry_sdk/**`
- `MIGRATION_GUIDE.md`
- `CHANGELOG.md`This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.
![sentry-warden[bot]](https://avatars.githubusercontent.com/in/2755838?s=60&v=4){kind=small}
Make docs-codebase-refresh manual-only (workflow_dispatch) to avoid competing PRs when both workflows fire on the same push. Switch incremental update from git diff to GitHub compare API to handle multi-commit pushes and shallow clone environments. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
sl0thentr0py
approved these changes
Mar 12, 2026
| ```bash | ||
| gh api repos/{owner}/{repo}/compare/{default_branch}...{after} --jq '.files[].filename' | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Bug: The docs-codebase-update workflow is set to workflow_dispatch but its instructions use {before} and {after} SHAs, which are only available in push events, breaking its functionality.
Severity: HIGH
Suggested Fix
The workflow's trigger and instructions are mismatched. Either re-enable the push trigger in the workflow's on: block to provide the {before} and {after} SHAs, or update the instructions in docs-codebase-update.md to not rely on these push-event-specific variables for manual runs. For example, the manual workflow could prompt for a commit range.
Prompt for AI Agent
Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.
Location: .github/workflows/docs-codebase-update.md#L53
Potential issue: The `docs-codebase-update` workflow is configured to run only on
`workflow_dispatch` (manual trigger). However, its instructions direct the AI agent to
use the command `gh api .../compare/{before}...{after}`. The `{before}` and `{after}`
placeholders are populated by `github.event.before` and `github.event.after` context
variables, which are only available during `push` events. When triggered manually, these
variables are null, causing the API call to fail or return no changed files. This
prevents the workflow from identifying which files have changed, defeating its core
purpose of performing incremental documentation updates.
Both workflows are now workflow_dispatch only. The push trigger for docs-codebase-update can be re-enabled once initial docs are generated and validated. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
dingsdax
force-pushed
the
feat/docs-codebase-agentic-workflows
branch
from
26b7f92 to
d41123b
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
gh aw) that auto-generate and maintain developer-facing codebase documentation indocs/codebase/docs-codebase-refresh: full regeneration of every doc page, triggered on merge to main/master or manual dispatchdocs-codebase-update: incremental update of only affected pages, triggered on merge whensentry_sdk/**,MIGRATION_GUIDE.md, orCHANGELOG.mdchangeBUILD_PLAN.mddesigned for reuse across other Sentry SDKs -- only the SDK Context block changes per language (will remove later)How This Relates to Other Sentry Docs
docs/codebase/*(this) explains what was built and how it works -- architecture, data flow, how modules connect, and why. Generated from full source analysis, not just docstrings. Aimed at SDK contributors and maintainers.Files added
docs/codebase/BUILD_PLAN.mddocs/codebase/_meta/style-guide.mddocs/codebase/_meta/manifest.json.github/workflows/docs-codebase-refresh.md.github/workflows/docs-codebase-update.md.github/workflows/docs-codebase-*.lock.yml.gitattributesdocs/codebase/**aslinguist-generatedTest plan
gh aw compileproduces 0 errors, 0 warnings for both workflowsgh aw run docs-codebase-refreshgenerates initial docs_MIN_VERSIONS🤖 Generated with Claude Code