Skip to content

Conversation

Copy link
Contributor

Copilot AI commented Jan 18, 2026

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

  • Schedule: Daily with fuzzy scheduling (scattered to reduce load spikes)
  • Timeout: 15 minutes
  • Skip-if-match: Prevents duplicate PRs when one is already open
  • Safe-outputs: create-pull-request with labels [documentation, ai-generated], reviewer copilot

Tools

  • github toolset for API access
  • edit for documentation changes
  • bash with all commands allowed for flexible commit analysis

Documentation Scope

The agent autonomously explores all documentation files in /docs/ and *.md files in the repository root to identify what needs updating.

Agent Task Flow

  1. Gather recent changes from past 7 days
  2. Identify documentation gaps
  3. Review current documentation
  4. Verify code examples still work
  5. Create PR with changes
Original prompt

This section details on the original issue you should resolve

<issue_title>[plan] Implement Documentation Maintainer workflow</issue_title>
<issue_description>## Objective

Create a daily workflow that reviews documentation files (16+ docs) and creates PRs to keep them synchronized with code changes.

Context

The repository has 16+ documentation files (/docs/, README.md, AGENTS.md) that drift out of sync with code. Recent examples:

  • PR feat: remove Docker-in-Docker support #205 removed Docker-in-Docker but MCP configuration docs still referenced it
  • Architecture changes to iptables rules aren't reflected in security documentation
  • CLI flag additions aren't consistently documented

As a security-critical tool, accurate documentation is essential for safe usage.

Approach

  1. Create workflow file: .github/workflows/doc-maintainer.md
  2. Configure triggers:
    • Daily schedule
    • Manual workflow_dispatch
  3. Review recent changes: Analyze git commits from past 7 days
  4. Identify documentation gaps:
    • Architecture changes (Docker, containers, networking)
    • API changes (CLI flags, env vars, configuration options)
    • Usage examples (MCP setup, firewall rules, domain whitelisting)
    • Security guidance (capabilities, iptables, Squid config)
  5. Create PR with updates:
    • Focus on critical docs first: /docs/mcp-config.md, README.md, AGENTS.md
    • Ensure code examples execute correctly
    • Update version numbers when applicable
    • Keep examples minimal and focused

Files to Create/Modify

Priority Documentation Files

  1. /docs/mcp-config.md - MCP server configuration (CRITICAL - frequently outdated)
  2. /docs/architecture.md - Container and network architecture
  3. /docs/usage.md - CLI usage and examples
  4. README.md - Overview and quick start
  5. AGENTS.md - Agent development guidelines
  6. /docs/logging.md - Logging configuration

Acceptance Criteria

  • Workflow runs daily at scheduled time
  • Reviews git commits from past 7 days
  • Identifies documentation that needs updates
  • Creates PR with synchronized documentation
  • Verifies code examples are valid
  • Completes within 15 minutes timeout
  • Labels PRs with documentation, ai-generated

Success Metrics

AI generated by Plan Command for discussion #328

Comments on the Issue (you are @copilot in this section)

Custom agent used: create-agentic-workflow
Design agentic workflows using GitHub Agentic Workflows (gh-aw) extension with interactive guidance on triggers, tools, and security best practices.


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
Copilot AI changed the title [WIP] Implement documentation maintainer workflow feat: add doc-maintainer workflow for daily documentation sync Jan 18, 2026
Copilot AI requested a review from Mossaka January 18, 2026 01:47
@Mossaka Mossaka marked this pull request as ready for review January 18, 2026 21:21
@github-actions
Copy link

github-actions bot commented Jan 18, 2026

✅ Coverage Check Passed

Overall Coverage

Metric Base PR Delta
Lines 77.88% 77.88% ➡️ +0.00%
Statements 77.94% 77.94% ➡️ +0.00%
Functions 77.29% 77.29% ➡️ +0.00%
Branches 71.00% 71.00% ➡️ +0.00%

Coverage comparison generated by scripts/ci/compare-coverage.ts

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

Unpinned 3rd party Action 'Documentation Maintainer' step
Uses Step
uses 'githubnext/gh-aw/actions/setup' with ref 'v0.36.0', not a pinned commit hash
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

Unpinned 3rd party Action 'Documentation Maintainer' step
Uses Step
uses 'githubnext/gh-aw/actions/setup' with ref 'v0.36.0', not a pinned commit hash
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

Unpinned 3rd party Action 'Documentation Maintainer' step
Uses Step
uses 'githubnext/gh-aw/actions/setup' with ref 'v0.36.0', not a pinned commit hash
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

Unpinned 3rd party Action 'Documentation Maintainer' step
Uses Step
uses 'githubnext/gh-aw/actions/setup' with ref 'v0.36.0', not a pinned commit hash
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

Unpinned 3rd party Action 'Documentation Maintainer' step
Uses Step
uses 'githubnext/gh-aw/actions/setup' with ref 'v0.36.0', not a pinned commit hash
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

Unpinned 3rd party Action 'Documentation Maintainer' step
Uses Step
uses 'githubnext/gh-aw/actions/setup' with ref 'v0.36.0', not a pinned commit hash
Comment on lines 17 to 23
bash:
- "git log:*"
- "git diff:*"
- "git show:*"
- "find . -name '*.md':*"
- "cat *"
- "grep -r:*"
Copy link
Collaborator

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

Copy link
Contributor Author

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.

Comment on lines 51 to 62
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
Copy link
Collaborator

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.

Copy link
Contributor Author

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.

Comment on lines 70 to 86
```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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot delete those details

Copy link
Contributor Author

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.

Comment on lines 92 to 108
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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot delete those details

Copy link
Contributor Author

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.

Comment on lines 114 to 123
```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
```
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot delete those details

Copy link
Contributor Author

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>
Copilot AI requested a review from Mossaka January 18, 2026 21:26
@github-actions
Copy link

🔒 Security Review: Unrestricted Bash Access Concern

I've reviewed this PR and identified a security concern related to the bash tool configuration.

Issue: Unrestricted Bash Command Access

Severity: Medium-High
Location: .github/workflows/doc-maintainer.md, lines 18-19

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 Concerning

What the agent needs for documentation maintenance:

  • git log - to see recent commits
  • grep, cat, head, tail - to read files and search
  • find, ls - to locate files
  • wc - to count changes

What unrestricted bash also allows:

  • curl - fetch and execute arbitrary content from allowed domains (github.com, raw.githubusercontent.com, registry.npmjs.org)
  • chmod/chown - modify file permissions
  • rm -rf - delete files before PR creation
  • Complex shell pipelines that could obfuscate malicious behavior
  • Git configuration manipulation

Attack Scenarios

While the firewall restricts network access to approved domains, the combination of:

  1. Unrestricted bash + Repository write access (edit tool) + PR creation (create-pull-request) + Daily automated execution

Creates potential attack vectors:

  • Agent could download malicious scripts from allowed domains and execute them
  • Agent could modify security-critical files (iptables rules, Squid config, seccomp profiles) before creating a PR
  • Agent could use bash to manipulate documentation in ways that mislead users about security features
  • Agent could exfiltrate data through network requests to allowed domains

Recommendations

Option 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:

  • Require manual review before merging any PRs created by this workflow
  • Add security scanning of generated PRs (check for changes to security-critical files)
  • Limit edit tool scope to /docs/ and *.md files only
  • Add audit logging of all bash commands executed

Option 3: Accept the risk with documentation:

  • Document why unrestricted bash is necessary (what specific commands are needed that aren't in the restricted list?)
  • Document security controls in place
  • Document monitoring for misuse

Question for Maintainers

What 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.

AI generated by Security Guard

@Mossaka Mossaka merged commit e2ad097 into main Jan 18, 2026
38 checks passed
@Mossaka Mossaka deleted the copilot/add-doc-maintainer-workflow branch January 18, 2026 22:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[plan] Implement Documentation Maintainer workflow

2 participants