AegisGitea-MCP/docs/write-mode.md

Write Mode

Threat Model

Write mode introduces mutation risk (issue/PR changes, metadata updates). Risks include unauthorized action, accidental mass updates, and audit evasion.

Default Posture

• WRITE_MODE=false by default.
• When enabled, writes require repository whitelist membership by default.
• Optional opt-in: WRITE_ALLOW_ALL_TOKEN_REPOS=true allows writes to any repo the token can access.
• Policy engine remains authoritative and may deny specific write tools.

Supported Write Tools

• create_issue
• update_issue
• create_issue_comment
• create_pr_comment
• add_labels
• assign_issue

Not supported (explicitly forbidden): merge actions, branch deletion, force push.

Enablement Steps

1. Set WRITE_MODE=true.
2. Choose one:
   • WRITE_REPOSITORY_WHITELIST=owner/repo,... (recommended)
   • WRITE_ALLOW_ALL_TOKEN_REPOS=true (broader scope)
3. Review policy file for write-tool scope.
4. Verify audit logging and alerting before rollout.

Safe Operations

• Start with one repository in whitelist.
• Use narrowly scoped bot credentials.
• Require peer review for whitelist/policy changes.
• Disable write mode during incident response if abuse is suspected.

Risk Tradeoffs

Write mode improves automation and triage speed but increases blast radius. Use least privilege, tight policy, and strong monitoring.