Designing Approval-Gated AI Agents for External Publishing in GitHub Community Agent

Introduction I maintain the GitHub Community Agent, an open-source Windows desktop application designed to assist maintainers in managing GitHub communities through AI-assisted review and drafting. A key focus of this project is the design of approval-gated AI agents that generate content for external publishing platforms while ensuring strict human oversight and security. This article explores the architectural principles and implementation techniques behind these approval-gated AI agents, particularly as developed for the upcoming V2 Promotion feature of GitHub Community Agent. The design balances AI automation with explicit human review to prevent unintended or unauthorized publishing actions. Background: GitHub Community Agent and V2 Promotion The GitHub Community Agent is currently released as a pre-release version 1.0.0-rc1 (see release details). It provides read-only AI-assisted community management capabilities on Windows, including reviewing GitHub Issues and Discussions, drafting replies for human review, and generating community reports. Importantly, V1 does not include any capability to write or publish content back to GitHub or other platforms. The V2 Promotion feature, under active development but not yet released, introduces AI agents that can draft and publish content to various external social and community platforms, including GitHub Discussions, Bluesky, DEV Community, Reddit, and Developer Forums. This feature is designed with a rigorous approval gating and security model to ensure that AI-generated content is only published after explicit human approval and verification. Architecture of Approval-Gated AI Agents Single Promotion Agent with Multiple Work Types The V2 Promotion system is architected around a single Promotion Agent and a shared engine (PromotionService) that supports multiple independently selectable Work Types. Each Work Type corresponds to a specific social platform or publishing channel, such as: GitHub Discussions (released and verified) Repository Optimization (released and verified) Bluesky (released and verified) DEV Community (in development, not verified) Reddit Promotion (development, not verified) Developer Forums (development, not verified) Each Work Type has its own task definition and expected publishing workflow, but all share the same underlying infrastructure for research, planning, drafting, approval, publishing, monitoring, and improvement. Strict Release Gate for Work Types Only Work Types with real-world acceptance evidence are included in official release builds. Others remain hidden or disabled unless running from source with explicit developer flags. This ensures that only thoroughly tested and verified publishing channels are enabled for automated or semi-automated use. Workflow Steps with Explicit Approval The publishing workflow for each Work Type follows these steps: Research: The agent reads public repository data, including facts, README, and recent releases. No writing occurs at this stage. Plan: The AI generates a plan outlining audience, value proposition, channels, schedule, and measurable objectives. Statements are marked as Verified (with source) or Proposed. Draft: The AI produces a draft message or post based strictly on evidence and repository data. Review and Approve: A human user reviews and edits the draft. Approval is explicit and exact: the approved content is fingerprinted, including repository, channel, title, and body. Any edit cancels approval. Publish: For GitHub Discussions, publishing is automated after a final permission check and confirmation. For other platforms, publishing is manual or semi-automated, requiring user action. Monitor: The system reads engagement metrics and feedback where supported. Improve: AI suggests improvements based on measured engagement, but never publishes automatically. This workflow ensures that no AI-generated content is published without explicit human consent and verification. Content Quality and Compliance Rules All Work Types share a strict rule set to ensure content quality and compliance: Facts only from authoritative evidence, with GitHub API data overriding conflicting README text. No invented features, metrics, testimonials, or endorsements. No engagement bait, incentives, or requests for votes, stars, or follows. Platform-specific constraints, such as title length, tag limits, and content format. Affiliation disclosure at the start of each post. No cross-posting or multiple posts per community. Output completeness checks and automatic retries for incomplete or filtered content. These rules are programmatically enforced during generation, approval, and publishing stages. Security and Isolation Measures The system incorporates multiple security and isolation mechanisms: Task Binding: Each task is bound to a specific repository; actions are checked against this binding. Token Management: Tokens for platform access are stored encrypted and scoped per repository, never shared or sent to AI models. Least Privilege: Tokens are restricted to minimal scopes needed for the task. Permission Re-Checks: Before publishing, permissions and repository settings are re-verified. Durable Outbox and Idempotency: Publishing actions are tracked with unique keys to prevent duplicate posts and enable verification. Fixed GraphQL Documents: Only a fixed set of GraphQL queries/mutations are allowed; AI-generated text is variable data inserted after approval. Audit Logging: All actions are logged in append-only audit records for traceability. These measures prevent unauthorized publishing and ensure accountability. Implementation Techniques Fingerprinting and Exact Approval Approval gating relies on fingerprinting the exact content to be published, including repository, channel, title, body, and category (for GitHub Discussions). This fingerprint is stored and checked at publish time to ensure the content has not changed since approval. Any user edit invalidates the approval, requiring re-approval. This technique prevents accidental or malicious publishing of unreviewed content. Separate Tokens and Encrypted Storage Tokens for each repository and platform are stored separately and encrypted using Windows DPAPI. This isolation prevents token leakage and enforces least privilege. Tokens are never exposed to the AI model or API responses, maintaining security boundaries. Controlled Publishing APIs Publishing is performed only via fixed GraphQL mutations with known parameters. The AI model only generates text content, which is inserted after approval. For GitHub Discussions, publishing is automated after final confirmation. For other platforms like DEV Community or Reddit, publishing is manual or semi-automated, with the system providing drafts and checklists but not posting directly. Monitoring and Improvement Without Publishing Post-publication monitoring reads engagement data where available (e.g., comments, upvotes). AI-generated improvement suggestions are offered but never published automatically, maintaining human control. Conclusion The GitHub Community Agent’s design of approval-gated AI agents for external publishing demonstrates a careful balance between AI assistance and human oversight. By enforcing explicit, exact approval, strict content rules, and robust security measures, the system ensures that AI-generated content is safe, accurate, and compliant before it reaches external platforms. This architecture can serve as a model for other AI-assisted publishing tools that require strong governance and trustworthiness. This article was written with the help of AI and reviewed and approved by the maintainer of the GitHub Community Agent project before publication. For more details, see the V2 Promotion documentation.