GitHub Agentic Workflows guide — how much it restricts coding agents in GitHub Actions

1. Executive summary

First, some terms. GitHub Actions is GitHub's automation service that runs workflows in response to repository events. A coding agent is a program that takes natural-language instructions, reads files, runs commands and works through multiple steps on its own; Copilot CLI, Claude Code and Codex are examples. Safe outputs are the mechanism by which the agent, instead of writing to GitHub directly, emits a structured request such as "create one issue"; a separate job that holds the write permissions validates and executes it. AI Credits (AIC) are GitHub Copilot's unit of usage-based billing; 1 AIC is one US cent. [1] [4]

Every number in this report is a default from GitHub's official docs, checked on 2026-09-16. We made no measurements of our own, and because the feature is in preview, defaults and commands may change. We kept what the docs describe as design separate from what they state as a guarantee.

2. What GitHub Agentic Workflows is

The official docs define it as "AI-powered repository automations that you define in markdown and run as GitHub Actions workflows." Where conventional Actions execute fixed conditions and commands exactly as written, an agentic workflow reads context such as an issue body or a CI log and decides what to do. The docs cite issue triage, automated PR review, CI failure investigation, documentation maintenance, code quality improvement and security review as uses. [1] [2]

It works in two stages. A workflow file consists of YAML frontmatter (when to run and what to allow) and a markdown body (natural-language instructions for the agent). Compiling the file with gh aw compile produces a .lock.yml next to it, and this lock file is what Actions actually runs. You commit both files. You can edit the markdown body on the GitHub website, but changing the frontmatter requires recompiling. [8]

Each engine authenticates differently. For Copilot, granting copilot-requests: write in the workflow permissions bills the organization through the default GITHUB_TOKEN. For the others you add a repository secret: ANTHROPIC_API_KEY for Claude Code, CODEX_API_KEY or OPENAI_API_KEY for Codex, and GEMINI_API_KEY for Gemini. The docs say Copilot has the broadest support for engine-specific features such as agent selection, a custom execution harness and resuming interrupted runs. That is the vendor's own description. [5]

3. Installation and a first workflow

The official quick start has five commands: install the extension, add a prebuilt workflow with a wizard, compile it, run it, and check its status. [7]

The table below summarizes the frontmatter of an example published on docs.github.com. The workflow reviews issue activity every Monday and creates one issue; the keys and values are exactly as in the docs. [12]

The body tells the agent to review the last 7 days of issue activity and create an issue with the number of opened and closed issues, recurring themes, issues that need attention, and two or three recommendations for maintainers, keeping it concise. The part that deserves attention is the frontmatter, not the body. The only write this workflow can make to the repository is creating one issue, and even that is not done by the agent: the agent leaves a request, and another job creates the issue. The sample repository githubnext/agentics has more workflows, such as issue triage, CI failure investigation, cost tracking and a daily malicious-code scan. The docs say: "Only import workflows from sources you trust, and review what a workflow does before adding it to your repository." [13] [12]

4. Control 1: read-only permissions and safe outputs

The security architecture doc describes these controls in three layers. The first layer is the runner plus container and virtualization isolation; the second is compile-time validation (schema checks, an expression allowlist, SHA pinning of actions); the third splits the run into separate stages at run time. This report treats the third layer as the most important. Paraphrasing the doc: the agent has no direct write access to external systems, and write operations run only in a separate job after the agent has finished. The agent job's default permissions are contents: read, issues: read and pull-requests: read. [3]

Writes go only through safe outputs. The frontmatter declares which write operations are allowed and the maximum number of each; during the run, the agent can only leave requests in those formats. The requests pass through a threat detection job and are then executed by a job that has write permissions. The docs' default caps are below. [4]

Defaults from the safe outputs reference. There are other kinds not in the table (updating and closing issues, creating discussions, milestones, updating releases, check runs and more), and most default to 1. The caps can be changed in the frontmatter.

Here is what this structure actually stops and what it does not. It stops an agent that has been fooled by its instructions or by an issue body from making arbitrary writes. A kind of write that was not declared has no job to execute it, and declared kinds still hit the count cap. It does not stop an allowed write from having the wrong content. If you allow one issue to be created, the structure does nothing about that issue's content being off the mark. The same goes for bad code in a PR if you allow PR creation. That part is left to the threat detection in section 5 and to human review. How to review PRs that AI created is covered in our report on the quality of AI-written code.

5. Control 2: network firewall, sandbox, threat detection

Network. If the frontmatter has no network:, network: defaults applies, which allows only basic infrastructure domains such as certificates, JSON schema, Ubuntu, major package mirrors and Microsoft domains. On top of that you can add ecosystem names such as python, node and github or individual domains, and take domains out with blocked. The Agent Workflow Firewall (AWF) enforces this network restriction. According to the architecture doc, it uses iptables to redirect HTTP and HTTPS traffic to a Squid proxy container that applies the domain allowlist, "to prevent data exfiltration." It is on by default for all engines and can be turned off, but the docs say to "keep it enabled in production." [14] [3]

Sandbox. The architecture doc describes the first layer as Docker, gVisor and KVM isolation on GitHub-hosted runners or Linux self-hosted runners, and the September 7 weekly update says the workflow runtime is being moved to Cloud Hypervisor-based microVMs. Our agent sandbox report covers why operational settings decide the outcome more than the relative strength of the isolation method itself. [3] [15]

Input sanitization. When text written by outsiders, such as an issue body, reaches the agent, @user mentions are wrapped in code formatting so no notification goes out, auto-linking phrases such as fixes #123 are neutralized, XML tags are rewritten into forms like (script), and URLs from untrusted domains are replaced with (redacted). These measures limit the impact of prompt injection (an attack that steers the agent with instructions hidden in external text); they do not eliminate injection itself. [3]

Threat detection. Before safe outputs are executed, a separate job inspects what the agent produced (issue, comment and PR bodies, and git patches). It checks for three things: prompt injection, secret leaks and malicious patches. By default, the same AI engine as the main workflow returns a JSON verdict. If a threat is found, the detection job fails and the safe output jobs are skipped. You configure it with threat-detection: on each output kind under safe-outputs in the frontmatter. Inside it, max-ai-credits sets a budget separate from the main agent's, and engine: false turns off the AI verdict so that only scanners you add yourself are used. The docs say: "Detection does not inherit the main agent’s budget — both caps apply independently to their respective jobs." [16]

The architecture doc also describes the limits of this design. If the first layer (runner and isolation) is breached, "higher-level security guarantees may not hold," and the doc states that compromise of hardware or cryptographic primitives, and side-channel and covert-channel attacks, are out of scope. Of the second layer it says: "Security violations arise due to misconfigurations, overly permissive specifications, and limitations of the declarative model." In other words, how strong the controls are comes down to how narrowly you write the frontmatter. [3]

6. Control 3: AI credits and cost structure

Cost has two parts: GitHub Actions minutes (runner time) and the engine's inference cost. Inference is counted in AI credits. GitHub Copilot moved to usage-based billing on June 1, 2026, and now counts credits by token usage instead of by number of requests. Copilot Pro includes $10 of credits in its $10 monthly fee, and Business includes $19 of credits in its $19 per-user fee. Code completions do not use credits. [17] The agentic workflows docs state 1 AIC = $0.01 and set the default caps below. [6]

Values from the cost management doc and the frontmatter reference. The dollar amounts are derived values we calculated at 1 AIC = $0.01. The daily cap of 5,000 AIC appears in the cost management doc's list of default guardrails, while the frontmatter reference describes the default of max-daily-ai-credits as disabled, so the two docs read differently. See section 9.

The $10 per run is a cap, not an expected cost. Actual usage depends on model pricing and context size. The docs give four ways to lower cost: use skip-if-match and skip-if-no-match to filter on conditions before the agent is started, so it does not run at all; use a cheaper model (gpt-4.1-mini and claude-haiku-4-5 are the examples); batch work into scheduled runs instead of reacting to every event; and set concurrency and rate limits. Actions minutes are billed per job, rounded up, so run time is cost. [6]

Who pays depends on the engine. With the Copilot engine, the copilot-requests: write permission draws on the organization's Copilot credits. With Claude, Codex and Gemini, each vendor bills the account behind the API key stored as a repository secret. The threat detection job also uses inference, so its cost is charged on top. [1] [16] General principles for cutting token cost are covered in our prompt caching report.

7. Where it fits and where it doesn't

Going by the docs and samples, the target is clear: repetitive work that is hard to handle with fixed rules alone but easy to undo when it goes wrong. That means labeling issues, reading CI failure logs and leaving likely causes as a comment, summarizing weekly activity in an issue, and proposing fixes to stale docs as a PR. Because the output is an issue, a comment or a PR, a person can look at it and throw it away.

This table is our judgment, based on the scope of the controls in the official docs and on the sample workflows. The docs have no list of what the feature is not suited for.

One more selection criterion: the feature has the least friction in organizations that already use Copilot. Authentication is handled by the GITHUB_TOKEN, billing rolls into the organization's credits, and, as the docs state, Copilot has the widest engine-specific feature support. If you use Claude Code or Codex as the engine, you have to put an API key in a secret and manage the cost separately. Either way, macOS runners cannot be used.

8. Checklist to apply today

• Start with one task that is easy to undo. Pick something whose result stays in an issue or a comment, such as issue labeling or a weekly summary. Import a sample with gh aw add-wizard githubnext/agentics/<name>, but read its frontmatter before adding it.
• Declare as few safe outputs as possible. Only the kinds you need, with the default count caps (mostly 1) left in place. When you enable create-pull-request, check the protected-files list.
• Start the network at defaults and add only the ecosystems you need. Do not turn off the firewall. If you need to open an internal API, add it by domain, and list what to exclude under blocked.
• Use a different engine for threat detection than for the main workflow. Under safe-outputs in the frontmatter, set another engine in the relevant output's threat-detection: engine:, or put your own scanner in front with steps.
• Set cost caps explicitly. Write max-ai-credits and max-daily-ai-credits into the frontmatter, and prefer scheduled runs over event triggers. For Actions minutes, run time is cost.
• Filter on trigger conditions first. Use skip-if-match so the agent is not started when label or title conditions do not match.
• Commit the lock file too, and recompile whenever you change the frontmatter. The .lock.yml is the file that actually runs. Because this is a preview, after gh aw upgrade you also need to update your workflows with gh aw update.
• Record cost and results. Like the sample Cost Tracker, log per-run spend in PRs, and count the share of suggestions that people actually adopted. If the adoption rate is low, narrow the trigger conditions before you rewrite the instructions.

9. What this is not yet

• This report summarizes the official docs; we made no measurements of our own. We could not find independent measurements of how much the controls actually stop, or of how many injections threat detection catches. The docs do not give a detection accuracy either.
• It is a public preview. GitHub itself says it is "subject to change," and the repository shipped five releases in the two days of September 13–14. The commands, keys and defaults in this report are as of 2026-09-16.
• The default daily cap reads differently depending on the doc. The cost management doc lists "5000 AI Credits per workflow per day" as a default guardrail, while the frontmatter reference describes the default of max-daily-ai-credits as disabled. You would need to run a workflow to confirm which of the two is the actual default.
• The Copilot credit allowances are the plan descriptions from GitHub's official blog, and the docs give no figure for how much of that allowance an agentic workflow run uses up. The per-run cap of 1,000 AIC is a cap, not an average.
• The official Korean-language docs appear to be machine-translated. The Korean edition of this report took its Korean terms for "agentic workflows" and "safe outputs" from those docs, but some of their sentences read awkwardly. For the exact meaning we relied on the English docs.
• The "good fit / poor fit" table in section 7 is our judgment. The docs only list uses; they have no list of poor fits.
• The sandbox migration (to microVMs) is a change in progress. The September 7 weekly update describes it as "moving the workflow fleet onto Cloud Hypervisor-based microVMs," and we could not confirm which runners it has reached, or when.
• We did not calculate the cost of Actions minutes, because it varies by runner type and plan.

10. Sources

All checked on 2026-09-16. Every source is GitHub's own documentation, changelog or repository: the vendor's description, not an independent measurement. This report reproduces defaults and commands as written and labels judgments as judgments.

Editorial basis: defaults and commands from the docs are reproduced as written; what each control stops and what it does not stop are written up separately; and where the docs give conflicting defaults, we did not decide which is right and left the conflict in the limits section.