Text of github.github.com › gh-aw › introduction › architecture as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Security Architecture | GitHub Agentic Workflows

Skip to main content Security Architecture GitHub Agentic Workflows (gh-aw) runs AI coding agents — GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini, or Pi — 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. Security Model Section titled “Security Model” Agentic Workflows (AW) adopts a layered approach that combines substrate-enforced isolation, declarative specification, and staged execution.

Each layer enforces distinct security properties under different assumptions and constrains the impact of failures above it. Threat Model Section titled “Threat Model” We consider an adversary that may compromise untrusted user-level components, e.g., containers, and may cause them to behave arbitrarily within the privileges granted to them. The adversary may attempt to: Access or corrupt the memory or state of other components Communicate over unintended channels Abuse legitimate channels to perform unintended actions Confuse higher-level control logic by deviating from expected workflows We assume the adversary does not compromise the underlying hardware or cryptographic primitives.

Attacks exploiting side channels and covert channels are also out of scope. Layer 1: Substrate-Level Trust Section titled “Layer 1: Substrate-Level Trust” AWs run on GitHub-hosted or Linux self-hosted GitHub Actions runners. Self-hosted deployments can include Actions Runner Controller (ARC) pods that use a privileged Docker-in-Docker (DinD) sidecar. The trusted substrate therefore includes the runner host or Kubernetes cluster, CPU, MMU, kernel, and container runtime.

With ARC DinD, the runner container sends Docker API commands to the sidecar daemon, which creates the agent, proxy, and MCP containers and enforces their Docker network boundaries. The default agent runtime uses Docker container isolation. Eligible GitHub-hosted runners can instead use Cloud Hypervisor to place the agent in a KVM-isolated microVM. These runtimes add isolation boundaries but do not remove trust in the runner host, firewall, MCP Gateway, container runtime, kernel, hypervisor, or hardware.

AWs also rely on three trusted infrastructure components: (1) a network firewall that configures connectivity and launches the agent, (2) an API proxy that routes model traffic and may hold endpoint-specific credentials or routing configuration for supported engines, and (3) an MCP Gateway that configures and spawns isolated MCP-server containers. Collectively, the substrate level provides memory and resource isolation, mediation of privileged operations and system calls, and explicit communication boundaries.

These guarantees hold even if an untrusted user-level component is fully compromised and executes arbitrary code. If this layer fails, higher-level security guarantees may not hold. Layer 2: Configuration-Level Trust Section titled “Layer 2: Configuration-Level Trust” AW trusts declarative configuration artifacts, e.g., Action steps, network-firewall policies, MCP server configurations, and the toolchains that interpret them to correctly instantiate system structure and connectivity.

The configuration level constrains which components are loaded, how components are connected, which communication channels are permitted, and what component privileges are assigned. Externally minted authentication tokens, e.g., agent API keys and GitHub access tokens, are a critical configuration input and are treated as imported capabilities that bound components’ external effects; declarative configuration controls their distribution, e.g., which tokens are loaded into which containers.

Security violations arise due to misconfigurations, overly permissive specifications, and limitations of the declarative model. This layer defines what components exist and how they communicate, but it does not constrain how components use those channels over time. Authored pre-activation, setup/post-steps, custom jobs, detection steps, and safe-output steps/actions are trusted executable code, not automatically confined to the agent sandbox.

Their effective job permissions, secrets, host mounts, and network access determine their authority. A read-only GITHUB_TOKEN does not remove other credentials or privileged host access. Domain allowlisting constrains destinations, not the safety of every request to an allowed service. Review these boundaries before deployment: Surface Author/operator responsibility Custom executable steps Keep untrusted event fields and downloaded content as data, not shell/JavaScript source.

Avoid eval and similar re-interpretation; environment indirection alone does not make later execution safe. Action and runtime pins Retain full commit SHA/digest pinning, update to reviewed patched releases, then recompile and review deployed locks. An immutable historical pin does not acquire later fixes. Policy opt-outs Review strict: false , skipped/suppressed lint, broader roles/bot admission, disabled sandbox/firewall/detection, and custom mounts or credentials as changes to the trust model.

Acknowledging a warning is not enforcement. Host and upstream state Apply the self-hosted host isolation checklist and cross-run artifact rules . Compilation does not prove host cleanliness, cache provenance, or producer-code trust. Layer 3: Plan-Level Trust Section titled “Layer 3: Plan-Level Trust” AW additionally relies on plan-level trust to constrain component behavior over time. At this layer, the trusted compiler decomposes a workflow into stages.

For each stage, the plan specifies (1) which components are active and their permissions, (2) the data produced by the stage, and (3) how that data may be consumed by subsequent stages. In particular, plan-level trust ensures that important external side effects are explicit and undergo thorough vetting. A primary instantiation of plan-level trust is the SafeOutputs subsystem. SafeOutputs is a set of trusted components that operate on external state.

An agent can interact with read-only MCP servers, e.g., the GitHub MCP server, but externalized writes, such as creating GitHub pull requests, are buffered as artifacts by SafeOutputs rather than applied immediately. When the agent finishes, SafeOutputs’ buffered artifacts can be processed by a deterministic sequence of filters and analyses defined by configuration. These checks can include structural constraints, e.g., limiting the number of pull requests, policy enforcement, and automated sanitization to ensure that sensitive information such as authentication tokens are not exported.

These filtered and transformed artifacts are passed to a subsequent stage in which they are externalized. Security violations at the planning layer arise from incorrect plan construction, incomplete or overly permissive stage definitions, or errors in the enforcement of plan transitions. This layer does not protect against failures of substrate-level isolation or mis-allocation of permissions at credential-minting or configuration time.

However, it limits the blast radius of a compromised component to the stage in which it is active and its influence on the artifacts passed to the next stage. Component Overview Section titled “Component Overview” The security architecture operates across multiple layers: compilation-time validation, runtime isolation, permission separation, network controls, and output sanitization. The following diagram illustrates the relationships between these components and the flow of data through the system. flowchart TB subgraph Input[" Input Layer"] WF[/"Workflow (.md)"/] IMPORTS[/"Imports & Includes"/] EVENT[/"GitHub Event<br/>(Issue, PR, Comment)"/] end subgraph Compile[" Compilation-Time Security"] SCHEMA["Schema Validation"] EXPR["Expression Safety Check"] PIN["Action SHA Pinning"] SCAN["Security Scanners<br/>(acti

The rest of this page is on the live site.