GitHub Agentic Workflows

The agent itself never holds write access to GitHub. The compiler rejects any write permission on the agent job, the GitHub tools it gets are forced read-only, and the tokens for the model provider and the GitHub tool server are kept out of the agent's container. Writes the workflow author has configured run later, in a separate job that gets only the write permissions those outputs need, using GitHub's per-job token that expires with the job. What keeps this short of the top is that custom tool servers receive whatever secrets the author hands them, and if a repository has a personal access token saved as GH_AW_GITHUB_TOKEN, it is used silently in place of the scoped per-job token.

There is no human approval step on the agent's actions by default. Issues, comments and pull requests the agent asks for are queued, checked against the configured output types and counts, and reviewed by a second AI model looking for threats, but that reviewer is a model, not a person. Code changes still reach the main branch only through a pull request that a human merges. An opt-in setting can require a human to approve each run through a GitHub environment, but that is one approval for the whole run before the agent starts, not a review of each action.

The actions that change things outside the sandbox are narrow, typed tools (create an issue, add a comment, open a pull request). They are validated in code: an unknown output type is rejected, each type has a maximum count, target repositories must be on an allowlist, and text is cleaned before posting. Inside the sandbox, though, the default tool set gives the agent an unrestricted shell and file editing, and network access is limited only by a domain allowlist.

Everything the agent runs happens inside the Agent Workflow Firewall container, on a private network whose only way out is a proxy that enforces a domain allowlist, on a GitHub runner that is thrown away after the job. The runner's model and GitHub tokens are explicitly kept out of the container, tool servers must run in their own containers, and the run fails rather than falling back to running on the host. Turning the sandbox off needs a dangerously named feature flag and is refused in strict mode, which is on by default. The container's own hardening (user, capabilities, seccomp) is configured in the separate gh-aw-firewall project and could not be verified here. The agent's container can also write to the shared /tmp/gh-aw directory that later host steps read.

gh-aw assumes the agent may be manipulated and limits what that achieves: the agent has no write credentials, its requested writes are typed, counted and reviewed by a second model, links to non-allowlisted domains are stripped from posted text, and on public repositories GitHub content from people without write access is filtered out before the model sees it. Only users with write access or above can trigger it by default. A manipulated agent can still read whatever the repository token can read and could try to send it out through one of the allowlisted domains using credentials an attacker plants in the content, and on private repositories the author filter is off by default.

By default there is no memory between runs; cache and repository memory are opt-in, and when used with threat detection the cache is only saved after detection passes. Instruction files such as AGENTS.md are loaded from the checked-out repository without a prompt, but for pull-request runs gh-aw restores agent configuration folders and root instruction files from the trusted base branch and deletes a PR-supplied .mcp.json. An agent that wants to change these files has to open a pull request, which a human must merge, and changes to protected files trigger a review request. Instruction files nested deeper in a pull-request checkout are not restored.

The components gh-aw loads by default are GitHub's own (Copilot CLI, the GitHub MCP server, the firewall images) and are pinned: the CLI is checked against a SHA256 checksum and container images are pinned by digest in the compiled workflow. Plugins are checked out at a pinned commit, and custom stdio tool servers must run in their own containers. Custom container images are only pinned when a digest is already known, otherwise they run by tag. Adding an extension requires editing and recompiling the workflow.

Credentials are kept out of the agent: the model-provider token is held by a separate API proxy and the GitHub tool token by the MCP gateway, so the model never sees them. Before any logs or outputs are uploaded, files are scanned and known secret values plus common token patterns are redacted, and this runs even when the job fails. Exporting telemetry is off unless the operator sets an endpoint. The Copilot token is still a long-lived personal access token, though narrowly scoped, and an optional GH_AW_GITHUB_TOKEN PAT can be broad.

Each run leaves a substantial record: GitHub Actions job logs, the agent's own logs, the tool server gateway's logs, firewall and proxy logs of network requests and model usage, and the structured list of outputs the agent asked for, tied together with the run ID and trace attributes. Exporting to an OpenTelemetry collector is supported once an endpoint is configured. Several of these logs sit in /tmp/gh-aw, which the agent's container can write to, so a compromised agent could alter them before they are uploaded. Logging is best-effort and actions do not wait for their record to be written.

Runs have firm limits by default: the agent step times out after 20 minutes, a separate API proxy outside the agent caps each run at 1,000 AI credits and 500 model calls, each workflow has a daily cap of 5,000 credits, and every output type has a maximum count. Because the cap is enforced in the proxy, sub-agents and anything else the agent starts count against the same budget, and the model cannot raise it. Cancelling the workflow stops the job through GitHub Actions. These limits can be raised by the operator through repository variables without any hard ceiling.