Add documentation synchronization workflow #323

Copilot · 2026-01-17T20:57:02Z

Creates an agentic workflow that monitors for code-documentation drift and creates issues to keep documentation synchronized with code changes. This is critical for this security-focused firewall tool where outdated docs create risk.

Files Added

.github/workflows/docs-sync.md - Agentic workflow definition
.github/workflows/docs-sync.lock.yml - Compiled GitHub Actions workflow (generated via gh aw compile)

Workflow Configuration

Triggers:

Daily schedule
Pull requests changing src/**/*.ts, containers/**, docs/**
Manual workflow_dispatch

Safe-outputs:

Creates up to 3 issues with [docs] prefix and documentation label

Timeout: 10 minutes

Agent Focus Areas

CLI usage and flags in README.md vs src/cli.ts
Security configuration examples in docs/security.md
Container documentation matching actual Dockerfiles
Version and compatibility information

The workflow follows the same patterns as existing agentic workflows like security-guard.md and plan.md.

Original prompt

This section details on the original issue you should resolve

<issue_title>[plan] Create documentation sync workflow</issue_title>
<issue_description>## Objective

Create an agentic workflow that monitors for code-documentation drift and creates issues or PRs to keep documentation synchronized with code changes.

Context

This is a security-critical firewall tool with 17+ documentation files. Documentation drift creates security risks when users rely on outdated configuration examples or security guidelines. Manual synchronization is error-prone.

Approach

Create .github/workflows-agentic/docs-sync.md workflow with:

Triggers:

Daily schedule

Pull request changes to core files (src/, containers/)

Manual workflow_dispatch

Workflow should:

Detect code changes that impact documentation

Review relevant doc files for outdated information

Identify specific sections needing updates

Create issues for needed updates OR create PRs for simple fixes

Focus Areas:

Security configuration examples in docs/

CLI usage and flags in README.md

Container documentation matching actual Dockerfiles

Version numbers and compatibility information

Domain whitelisting examples

Files to Create/Modify

Create: .github/workflows-agentic/docs-sync.md

Reference: Existing security-guard.md for workflow structure

May need: Helper scripts in scripts/ci/ if complex analysis needed

Acceptance Criteria

Workflow file created with appropriate triggers

Detects changes to core code files (src/squid-config.ts, src/docker-manager.ts, containers/)

Reviews documentation files for outdated content

Creates issues with specific recommendations OR creates PRs for simple fixes

Safe-outputs configured with appropriate limits (max 3 issues)

Tested with workflow_dispatch trigger

At least one successful execution documented

Example Workflow Structure
---
description: Documentation synchronization based on code changes
on:
  schedule: daily
  pull_request:
    paths: ['src/**/*.ts', 'containers/**', 'docs/**']
  workflow_dispatch:
permissions:
  contents: read
  pull-requests: read
tools:
  github:
    toolsets: [default]
safe-outputs:
  create-issue:
    title-prefix: "[docs] "
    labels: [documentation]
    max: 3
timeout-minutes: 10
---
Related to #313

AI generated by Plan Command for discussion #304

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

Fixes [plan] Create documentation sync workflow #315

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

Mossaka · 2026-01-18T01:36:02Z

@copilot generate the github action yamls and push

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

Copilot · 2026-01-18T01:38:44Z

@copilot generate the github action yamls and push

Generated docs-sync.lock.yml using gh aw compile and pushed in commit 26d6b7a.

github-actions · 2026-01-18T02:13:20Z