-
Notifications
You must be signed in to change notification settings - Fork 2
feat: add doc-maintainer workflow for daily documentation sync #341
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
✅ Coverage Check PassedOverall Coverage
Coverage comparison generated by |
| comment_repo: "" | ||
| steps: | ||
| - name: Setup Scripts | ||
| uses: githubnext/gh-aw/actions/setup@v0.36.0 |
Check warning
Code scanning / CodeQL
Unpinned tag for a non-immutable Action in workflow Medium
Uses Step
| output_types: ${{ steps.collect_output.outputs.output_types }} | ||
| steps: | ||
| - name: Setup Scripts | ||
| uses: githubnext/gh-aw/actions/setup@v0.36.0 |
Check warning
Code scanning / CodeQL
Unpinned tag for a non-immutable Action in workflow Medium
Uses Step
| total_count: ${{ steps.missing_tool.outputs.total_count }} | ||
| steps: | ||
| - name: Setup Scripts | ||
| uses: githubnext/gh-aw/actions/setup@v0.36.0 |
Check warning
Code scanning / CodeQL
Unpinned tag for a non-immutable Action in workflow Medium
Uses Step
| success: ${{ steps.parse_results.outputs.success }} | ||
| steps: | ||
| - name: Setup Scripts | ||
| uses: githubnext/gh-aw/actions/setup@v0.36.0 |
Check warning
Code scanning / CodeQL
Unpinned tag for a non-immutable Action in workflow Medium
Uses Step
| activated: ${{ (steps.check_membership.outputs.is_team_member == 'true') && (steps.check_skip_if_match.outputs.skip_check_ok == 'true') }} | ||
| steps: | ||
| - name: Setup Scripts | ||
| uses: githubnext/gh-aw/actions/setup@v0.36.0 |
Check warning
Code scanning / CodeQL
Unpinned tag for a non-immutable Action in workflow Medium
Uses Step
| process_safe_outputs_temporary_id_map: ${{ steps.process_safe_outputs.outputs.temporary_id_map }} | ||
| steps: | ||
| - name: Setup Scripts | ||
| uses: githubnext/gh-aw/actions/setup@v0.36.0 |
Check warning
Code scanning / CodeQL
Unpinned tag for a non-immutable Action in workflow Medium
Uses Step
.github/workflows/doc-maintainer.md
Outdated
| bash: | ||
| - "git log:*" | ||
| - "git diff:*" | ||
| - "git show:*" | ||
| - "find . -name '*.md':*" | ||
| - "cat *" | ||
| - "grep -r:*" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@copilot please allow all tools in bash
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done in 7942811 - removed all bash command restrictions, now allows all tools.
.github/workflows/doc-maintainer.md
Outdated
| Focus on these files in order of priority: | ||
|
|
||
| 1. `/docs/architecture.md` - Container and network architecture | ||
| 2. `/docs/usage.md` - CLI usage and examples | ||
| 3. `README.md` - Overview and quick start | ||
| 4. `AGENTS.md` - Agent development guidelines | ||
| 5. `/docs/logging_quickref.md` - Logging configuration | ||
| 6. `/docs/security.md` - Security documentation | ||
| 7. `/docs/troubleshooting.md` - Troubleshooting guides | ||
| 8. `/docs/environment.md` - Environment configuration | ||
| 9. `/docs/egress-filtering.md` - Egress filtering details | ||
| 10. `/docs/github_actions.md` - GitHub Actions integration |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@copilot just tell the agent to read all the files in /docs and all the *.md files no need to be specific. the agent can epxlore it by itself.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done in 7942811 - simplified to tell the agent to explore /docs/ and *.md files on its own.
.github/workflows/doc-maintainer.md
Outdated
| ```bash | ||
| # List commits from the past 7 days | ||
| git log --oneline --since="7 days ago" | ||
|
|
||
| # See which files changed | ||
| git log --since="7 days ago" --name-only --pretty=format:"" | ||
|
|
||
| # Get detailed changes for key source files | ||
| git log --since="7 days ago" -p -- src/ | ||
| git log --since="7 days ago" -p -- containers/ | ||
| ``` | ||
|
|
||
| Focus on changes to: | ||
| - `src/*.ts` - Core TypeScript implementation | ||
| - `containers/**` - Docker container configurations | ||
| - `.github/workflows/*.md` - Workflow definitions | ||
| - `package.json` - Dependencies and scripts |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@copilot delete those details
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done in 7942811 - removed the detailed bash command examples.
.github/workflows/doc-maintainer.md
Outdated
| 1. **Architecture Changes**: | ||
| - Docker container configuration changes → Update `/docs/architecture.md` | ||
| - Network topology changes → Update network diagrams and descriptions | ||
| - iptables rule changes → Update security documentation | ||
|
|
||
| 2. **CLI Changes**: | ||
| - New flags or options in `src/cli.ts` → Update `/docs/usage.md` and `README.md` | ||
| - Environment variable changes → Update `/docs/environment.md` | ||
| - Exit code changes → Update troubleshooting docs | ||
|
|
||
| 3. **MCP Configuration**: | ||
| - Changes to MCP server handling → Update `AGENTS.md` MCP sections | ||
| - Environment variable requirements → Update configuration examples | ||
|
|
||
| 4. **Security Updates**: | ||
| - Capability changes → Update `/docs/security.md` | ||
| - Firewall rule changes → Update egress filtering docs |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@copilot delete those details
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done in 7942811 - removed the detailed documentation gaps mapping.
.github/workflows/doc-maintainer.md
Outdated
| ```bash | ||
| # List all documentation files | ||
| find docs -name '*.md' -type f | ||
|
|
||
| # Read key files | ||
| cat README.md | ||
| cat AGENTS.md | ||
| cat docs/architecture.md | ||
| cat docs/usage.md | ||
| ``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@copilot delete those details
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done in 7942811 - removed the detailed review documentation section with bash examples.
Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
🔒 Security Review: Unrestricted Bash Access ConcernI've reviewed this PR and identified a security concern related to the bash tool configuration. Issue: Unrestricted Bash Command AccessSeverity: Medium-High Finding: The workflow grants unrestricted bash access to the AI agent: tools:
bash:While the PR description explicitly states this is intentional ("bash with all commands allowed for flexible commit analysis"), this creates security risks for a daily automated workflow with repository write access. Why This is ConcerningWhat the agent needs for documentation maintenance:
What unrestricted bash also allows:
Attack ScenariosWhile the firewall restricts network access to approved domains, the combination of:
Creates potential attack vectors:
RecommendationsOption 1 (Recommended): Restrict bash to specific safe commands: tools:
bash:
- "git"
- "grep"
- "find"
- "cat"
- "head"
- "tail"
- "wc"
- "ls"This provides all the functionality needed for commit analysis and documentation review without the security risks. Option 2: Keep unrestricted access but add safeguards:
Option 3: Accept the risk with documentation:
Question for MaintainersWhat specific bash commands beyond the basic set (git, grep, cat, find, ls, wc) are required for this workflow? If the answer is "none" or only a few additional commands, Option 1 (restricted allowlist) is the safest approach for a security-critical tool like AWF. Note: This is not a false alarm about code style - this is a genuine security boundary concern for a tool whose purpose is to provide security isolation for AI agents.
|
Creates a daily agentic workflow that reviews git commits from the past 7 days and creates PRs to synchronize documentation with code changes.
Workflow Configuration
create-pull-requestwith labels[documentation, ai-generated], reviewercopilotTools
githubtoolset for API accesseditfor documentation changesbashwith all commands allowed for flexible commit analysisDocumentation Scope
The agent autonomously explores all documentation files in
/docs/and*.mdfiles in the repository root to identify what needs updating.Agent Task Flow
Original prompt
✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.