was curious how gh-aw thinks about agent actions, especially when an agent wants to comment, open PRs, modify files, or call external tools.

[mdashrraf]

Hey, I’m exploring how agentic workflows are being designed inside CI environments. I was curious how gh-aw thinks about agent actions, especially when an agent wants to comment, open PRs, modify files, or call external tools. Are actions generally constrained by the GitHub Actions runtime, or is there a separate approval model you recommend?

[pelikhan]

/scout answer this question

[pelikhan]

/scout answer question

[github-actions]

🔭 Recon complete! Scout has charted the territory. Map ready! 🗺️

[github-actions]

🔍 Scout Research Report

Triggered by @pelikhan

Executive Summary

GitHub Agentic Workflows (gh-aw) uses a layered security model where agents are read-only by default, and all write operations (commenting, opening PRs, modifying files, calling external tools) go through a separate, vetted pipeline called Safe Outputs. Actions are constrained by both the GitHub Actions runtime and a dedicated approval architecture built on top of it.

Click to expand detailed findings

Research Findings

Default Permission Model: Read-Only

Agents run with minimal read-only permissions by default. This applies to all three supported agent engines (GitHub Copilot CLI, Claude Code, OpenAI Codex). The agent job is explicitly isolated from write access to the repository and GitHub APIs.

• Read access is provided via the GitHub MCP server (read-only mode)
• The agent can analyze issues, read code, search, and reason — but cannot directly push commits, open PRs, or post comments

Safe Outputs: The Write Approval Layer

Write operations are not blocked outright — they're deferred through the SafeOutputs subsystem:

1. Agent runs in its sandboxed job with read-only permissions
2. Write intents (e.g., "add a comment", "create a PR") are captured and buffered into an agent_output.json artifact — they're never directly executed
3. After the agent completes, a Threat Detection job analyzes the buffered output for:
   • Secret leaks (e.g., tokens accidentally included in a comment)
   • Malicious or unexpected content
   • Structural violations (e.g., too many PRs created at once)
4. Only if checks pass do scoped write jobs execute the approved operations via the GitHub API

This means even a fully compromised or prompt-injected agent cannot directly modify repository state — it can only request changes, which go through the vetting pipeline.

The safe output types currently supported include:

• add_comment — posting to issues/PRs/discussions
• create_issue — filing new issues
• add_labels — labeling issues/PRs
• create_pull_request — opening PRs

Additional Guardrails

Layer	Mechanism
Substrate	Sandboxed container, network firewall, no access to secrets
Configuration	SHA-pinned dependencies (supply chain security), tool allowlisting
Planning	Safe outputs buffer writes; separate jobs hold write permissions
Access control	Workflows can be gated to team members only
Human approval gates	For critical operations (e.g., merging to main), human review can be required

GitHub Actions Runtime vs. Safe Outputs

The GitHub Actions runtime alone provides some constraints (token scoping, environment isolation), but gh-aw adds a separate layer on top:

• Standard GitHub Actions: you'd typically pass GITHUB_TOKEN with write permissions directly to a step — the agent could use it freely
• gh-aw: the agent job runs with no write token; write permissions are only granted to the deterministic safe output jobs that run after agent analysis

This is explicitly noted in the gh-aw docs as an advantage over running coding agent CLIs directly in standard YAML workflows, which tends to grant more permission than needed for any specific task.

External Tool Calls (MCP Servers)

External tool use by agents is controlled via tool allowlisting. Agents can only call tools that are explicitly registered and permitted. The MCP configuration is defined at compile time in .github/mcp.json, so ad hoc or unanticipated tool use is blocked. Network isolation further limits what external services an agent can reach.

Recommendations

• For new workflows: Start with the default read-only model and only add safe output operations you actually need — the minimal footprint principle applies here
• For sensitive repos: Use team-gating and human approval gates for any workflow that can create PRs or push code
• For PR creation: Recognize that create_pull_request still requires human review before merge — it's a proposal, not a deployment
• Don't bypass SafeOutputs: Avoid the pattern of passing a write-scoped GITHUB_TOKEN directly to the agent; this defeats the architecture's core safety guarantee

Key Sources

• [GitHub Blog: Automate repository tasks with GitHub Agentic Workflows]((github.blog/redacted)
• Security Architecture | GitHub Agentic Workflows
• [ByteByteGo: The Security Architecture of GitHub Agentic Workflow]((blog.bytebytego.com/redacted)
• [The Register: GitHub previews Agentic Workflows]((www.theregister.com/redacted)

Suggested Next Steps

1. Read the Security Architecture page for full threat model details
2. Review .github/aw/github-agentic-workflows.md in this repo for the canonical system prompt given to agents
3. Explore the safe-outputs MCP server source to understand exactly which write operations are available and their limits

References:

• §25035390788

🔭 Intelligence gathered by Scout · ● 102.8K · ◷

[mdashrraf]

This is super helpful — appreciate the detailed breakdown.

The SafeOutputs pattern is interesting — especially the idea of separating intent from execution.

Curious if you’ve seen similar patterns needed beyond repos (e.g. agents triggering emails, APIs, or external workflows), or if most of the risk you’re seeing is still within GitHub itself?