Add workflow for daily documentation updates#132
Conversation
Creates a GitHub Agentic Workflow that runs daily on weekdays to identify documentation files that have drifted from recent code changes and opens a pull request with the necessary updates. Uses Copilot engine with GitHub MCP tools, bash, and edit tools. Read-only permissions with safe-outputs for PR creation. Co-authored-by: ewega <26189114+ewega@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds a GitHub Advanced Workflows (gh-aw) agentic workflow to periodically detect documentation drift in gh-devlake and open a single docs-only PR with fixes.
Changes:
- Added an agent prompt workflow (
docs-sync.md) describing how to detect stale docs and what files to update. - Added the compiled GitHub Actions workflow (
docs-sync.lock.yml) to run on a weekday schedule and via manual dispatch.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| .github/workflows/docs-sync.md | Defines the agent’s docs-sync task, constraints, and PR creation rules. |
| .github/workflows/docs-sync.lock.yml | Compiled workflow that executes the Copilot CLI agent on a schedule and handles safe outputs/PR creation. |
| set -o pipefail | ||
| # shellcheck disable=SC1003 | ||
| sudo -E awf --env-all --container-workdir "${GITHUB_WORKSPACE}" --allow-domains "api.business.githubcopilot.com,api.enterprise.githubcopilot.com,api.github.com,api.githubcopilot.com,api.individual.githubcopilot.com,github.com,go.dev,golang.org,goproxy.io,host.docker.internal,pkg.go.dev,proxy.golang.org,raw.githubusercontent.com,registry.npmjs.org,storage.googleapis.com,sum.golang.org,telemetry.enterprise.githubcopilot.com" --log-level info --proxy-logs-dir /tmp/gh-aw/sandbox/firewall/logs --enable-host-access --image-tag 0.23.0 --skip-pull --enable-api-proxy \ | ||
| -- /bin/bash -c '/usr/local/bin/copilot --add-dir /tmp/gh-aw/ --log-level all --log-dir /tmp/gh-aw/sandbox/agent/logs/ --add-dir "${GITHUB_WORKSPACE}" --disable-builtin-mcps --allow-all-tools --allow-all-paths --prompt "$(cat /tmp/gh-aw/aw-prompts/prompt.txt)"' 2>&1 | tee -a /tmp/gh-aw/agent-stdio.log |
There was a problem hiding this comment.
The Copilot CLI invocation uses --allow-all-tools --allow-all-paths, which doesn’t enforce the workflow’s “documentation-only / don’t modify Go source code” constraint. This increases the blast radius of a scheduled automation run (it can edit any repo file and run arbitrary tools). Consider restricting allowed tools/paths to docs-only targets (e.g., README.md, AGENTS.md, docs/**) so the workflow’s safety guarantee is enforced by configuration, not only by the prompt.
| -- /bin/bash -c '/usr/local/bin/copilot --add-dir /tmp/gh-aw/ --log-level all --log-dir /tmp/gh-aw/sandbox/agent/logs/ --add-dir "${GITHUB_WORKSPACE}" --disable-builtin-mcps --allow-all-tools --allow-all-paths --prompt "$(cat /tmp/gh-aw/aw-prompts/prompt.txt)"' 2>&1 | tee -a /tmp/gh-aw/agent-stdio.log | |
| -- /bin/bash -c '/usr/local/bin/copilot --add-dir /tmp/gh-aw/ --log-level all --log-dir /tmp/gh-aw/sandbox/agent/logs/ --add-dir "${GITHUB_WORKSPACE}" --disable-builtin-mcps --allow-tools filesystem,git,github,terminal --allow-paths "README.md,AGENTS.md,docs/**,.github/**" --prompt "$(cat /tmp/gh-aw/aw-prompts/prompt.txt)"' 2>&1 | tee -a /tmp/gh-aw/agent-stdio.log |
| mode: remote | ||
| toolsets: [default] | ||
| bash: true | ||
| edit: |
There was a problem hiding this comment.
tools.edit is declared but has no value (edit:). While valid YAML, it’s ambiguous whether the edit tool is intended to be enabled or configured (and future readers may assume it’s a mistake). Make this explicit (e.g., edit: true or provide the intended edit-tool configuration).
| edit: | |
| edit: true |
|
@copilot Please address the two Copilot review comments before merge: 1) restrict the docs sync workflow so docs-only safety is enforced by configuration instead of |
- Restrict bash to specific safe commands (git, cat, grep, find, ls, head, tail, wc) instead of bash: true — eliminates --allow-all-tools - Add engine.args --allow-paths to restrict file edits to README.md and docs/** only - Remove AGENTS.md from editable targets (compiler protects it) - Update prompt to clarify AGENTS.md is read-only Co-authored-by: ewega <26189114+ewega@users.noreply.github.com>
Addressed in e31f2ae:
Also removed Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
ewega
left a comment
ewega
left a comment
There was a problem hiding this comment.
Reviewed after follow-up fixes; safe to merge.
Adds a GitHub Agentic Workflow (gh-aw) that runs daily on weekdays to detect documentation drift in
gh-devlakeand open a single docs-only PR with fixes.Changes
.github/workflows/docs-sync.md): Defines the agent's docs-sync task — gathers recent code changes, compares againstREADME.mdanddocs/, edits stale sections, and opens a PR via safe-outputs..github/workflows/docs-sync.lock.yml): Auto-generated GitHub Actions YAML that runs the Copilot CLI agent on a fuzzy weekday schedule and via manual dispatch.Safety Configuration
contents: read,issues: read,pull-requests: read— all writes go throughsafe-outputs.create-pull-request.git,cat,grep,find,ls,head,tail,wcare allowed (no--allow-all-tools).engine.argsinjects--allow-paths "README.md,docs/**"to limit file edits to documentation targets only.AGENTS.mdis excluded from editable targets since the compiler'sprotected_fileslist blocks modifications to it. The agent reads it as a reference and notes drift in the PR body instead.Notes
edit:(null) syntax is the correct gh-aw format for enabling the edit tool —edit: trueis rejected by the compiler schema (requires null or object, not boolean).--allow-all-pathsautomatically for anysafe-outputs.create-pull-requestworkflow; the--allow-pathsflag fromengine.argsadds a more restrictive layer on top.🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.