Text of github.github.com › gh-aw › specs › safe-outputs-specification as Styx crawled it on Nov 19, 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

Safe Outputs MCP Gateway Specification | GitHub Agentic Workflows

Skip to main content Safe Outputs MCP Gateway Specification Version : 1.30.0 Status : Working Draft Publication Date : 2026-11-18 Editor : GitHub Agentic Workflows Team This Version : safe-outputs-specification Latest Published Version : This document Abstract Section titled “Abstract” This specification establishes normative requirements for the Safe Outputs Model Context Protocol (MCP) Gateway, a security-centric translation layer enabling AI agents to declare intended GitHub operations through structured protocols while maintaining strict privilege separation.

The gateway functions as an intermediary between read-only agent execution environments and permission-controlled execution contexts, providing configurable constraints, input validation, content sanitization, and preview capabilities. This document specifies behavioral requirements, security properties, operational semantics, and conformance criteria for implementing systems. Document Status Section titled “Document Status” This document represents a working draft specification subject to revision.

It documents the Safe Outputs MCP Gateway as implemented in GitHub Agentic Workflows version 1.8.0 and later. Future versions may introduce backwards-incompatible changes. Implementers should consult the latest version before beginning new implementations. This specification follows World Wide Web Consortium (W3C) formatting conventions while being independently maintained by the GitHub Agentic Workflows project. Table of Contents Section titled “Table of Contents” Introduction Conformance Requirements Security Architecture Structural Components Configuration Semantics Universal Feature Interpretation Safe Output Type Definitions Protocol Exchange Patterns Content Integrity Mechanisms Execution Guarantees Cache Memory Integrity Appendices Terminology Section titled “Terminology” This specification uses the following terms with precise definitions: Agent : The AI-powered process executing in an untrusted context with read-only GitHub permissions.

Safe Output Type : A category of GitHub operation (e.g., create_issue , add_comment ) with a corresponding MCP tool definition and handler implementation. MCP Gateway : The containerized stdio MCP server accepting MCP tool invocation requests and recording operations to NDJSON format. Runs in an isolated container alongside the agent job. Safe Output Processor : The privileged execution context that reads NDJSON artifacts, validates operations, and executes GitHub API calls.

Handler : JavaScript implementation processing operations of a specific safe output type. Validation : Pre-execution verification of operation structure, limits, and authorization. Includes schema validation, limit enforcement, and allowlist checking. Sanitization : Content transformation pipeline removing potentially malicious patterns while preserving legitimate content. Verification : Post-compilation checking of configuration integrity through hash validation.

Staged Mode : Preview execution mode where operations are simulated without creating permanent GitHub resources. Temporary ID : A workflow-scoped placeholder identifier using the form aw_<id> for a not-yet-created resource. A reference MAY appear in ordinary Markdown form or with a Markdown escape immediately before # , _ , or both (for example, #aw_track1 , \#aw_track1 , #aw\_track1 , or \#aw\_track1 ). Implementations MUST remove only those backslash escapes immediately preceding # or _ when normalizing a reference for lookup or emitted replacement.

They MUST preserve unrelated backslash escapes. A valid temporary-ID candidate MUST match the complete identifier form; implementations MUST NOT match a valid prefix of a longer or malformed identifier. Provenance : Metadata identifying the workflow and run that created a GitHub resource. Included in footers or API metadata fields. Integrity Level : A classification of the trust level assigned to a workflow run based on its guard policy.

The four levels in descending order of trust are: merged , approved , unapproved , and none . Policy Hash : An 8-character hexadecimal digest of the canonical form of a workflow’s guard policy fields ( blocked-users , min-integrity , repos , trusted-bots , trusted-users ). Used as part of the cache key to detect policy changes. Integrity Branch : A Git branch within the cache memory repository corresponding to a specific integrity level.

Each branch holds data written exclusively by runs at that integrity level. Cache Poisoning : A Bell-LaPadula write-up violation where a lower-integrity agent writes data to a shared cache store that is subsequently consumed by a higher-integrity run without provenance verification. Steering Issue : A run-scoped issue allocated during activation when safe-outputs.steer is enabled. It collects user-authored steering comments and is reused as the agent failure issue when the run fails.

1. Introduction Section titled “1. Introduction” 1.1 Motivation and Problem Statement Section titled “1.1 Motivation and Problem Statement” Contemporary AI-powered software workflows require actionable outcomes beyond informational responses. Agents must translate reasoning into concrete platform operations—creating issues for bugs, commenting on pull requests, managing labels. However, granting AI systems direct write access to version control platforms introduces severe security vulnerabilities: Prompt injection attacks : Adversarially-crafted inputs manipulate agent behavior, potentially causing unauthorized deletions, spam creation, or credential exfiltration Unbounded resource consumption : Compromised agents exhaust API rate limits, storage quotas, or workflow execution time Audit trail opacity : Direct API invocations obscure operation provenance, complicating incident response and compliance Credential surface expansion : Write-capable tokens become high-value targets, increasing attack surface Traditional mitigation strategies prove inadequate: Full prohibition eliminates automation benefits, relegating agents to advisory roles Manual approval gates create bottlenecks, defeating automation’s purpose Overly-permissive grants accept unacceptable risk for convenience The Safe Outputs MCP Gateway introduces a structured alternative: declarative operation requests with deferred, validated execution .

Agents articulate intentions through type-safe protocols; isolated execution contexts validate and fulfill requests under configured constraints. 1.2 Scope and Boundaries Section titled “1.2 Scope and Boundaries” Within Specification Scope : This document normatively defines: Security model architecture establishing privilege separation between untrusted reasoning and trusted execution Configuration schema semantics for declaring available operations, constraints, and validation rules Protocol exchange patterns governing operation declaration, validation, and fulfillment Content security requirements specifying sanitization, filtering, and validation transformations Operational guarantees characterizing atomicity, ordering, idempotency, and error handling for each safe output type MCP integration defining tool interface schemas and stdio container transport requirements Explicitly Out of Scope : This specification does NOT define: Core Model Context Protocol semantics (see external MCP specification) GitHub REST/GraphQL API implementation details (see GitHub API documentation) AI model selection, prompt engineering, or agent implementation strategies User interface design for workflow authoring or monitoring Container orchestration, deployment topology, or infrastructure provisioning Performance benchmarks or resource limits unrelated to specified safe-output security boundaries 1.3 Design Principles Section titled “1.3 Design Principles” Four foundational principles govern this specification: Principle P1: Security Through Architectural Separation Write permissions MUST reside in separate ex

The rest of this page is on the live site.