diff --git a/docs/src/assets/diagrams/architecture-2026-08-29.svg b/docs/src/assets/diagrams/architecture-2026-08-29.svg new file mode 100644 index 00000000000..420523a2380 --- /dev/null +++ b/docs/src/assets/diagrams/architecture-2026-08-29.svg @@ -0,0 +1,72 @@ + + Safe Outputs permission isolation + The read-only agent job writes an agent_output.json artifact. A threat detection job analyzes the artifact for secret leaks and malicious patches. If approved, separate scoped safe-output jobs (create_issue, add_comment, create_pull_request) call the GitHub API; the agent itself never holds write permissions. + + + + + + AGENT JOB + read-only permissions + + + AI Agent + + + agent_output.json + (artifact) + + + + + + + + + + + THREAT DETECTION + secret leaks + malicious patches + + + + + approved + + + + + blocked + + Workflow fails + + + + SAFE OUTPUT JOBS + scoped write permissions + + + create_issue + + + add_comment + + + create_pull_request + + + + + + + + + + + GitHub + API + + + + diff --git a/docs/src/content/docs/introduction/architecture.mdx b/docs/src/content/docs/introduction/architecture.mdx index 8347c2ff0d2..2e9783a41ec 100644 --- a/docs/src/content/docs/introduction/architecture.mdx +++ b/docs/src/content/docs/introduction/architecture.mdx @@ -11,6 +11,8 @@ head: --- import { Aside } from '@astrojs/starlight/components'; +import { Image } from 'astro:assets'; +import safeOutputsIsolation from '../../../assets/diagrams/architecture-2026-08-29.svg'; GitHub Agentic Workflows (gh-aw) runs AI coding agents — GitHub Copilot, Claude Code, OpenAI Codex, or Google Gemini — inside GitHub Actions with a defense-in-depth security architecture that protects against prompt injection, rogue MCP servers, and compromised agents. This document provides an overview of the security model and its key components. @@ -165,6 +167,8 @@ flowchart LR LABEL --> API ``` +Diagram showing the agent job writing an agent_output.json artifact, which a threat detection job analyzes for secret leaks and malicious patches; only when approved do scoped safe-output jobs such as create_issue, add_comment, and create_pull_request call the GitHub API, while the agent itself never holds write permissions +