Use Agentic Workflows when a repository job means reading text and making a call, like sorting issues or explaining a failed CI run. Skip them for builds, tests and deploys, where the same steps must run the same way every time. GitHub made the tool generally available on October 28, 2026.
The short answer
- What it is: an open source project from GitHub Next. You write the goal in Markdown, and the gh aw CLI extension compiles it into a standard Actions workflow.
- Use it for: issue triage, CI failure analysis, documentation updates and test writing.
- Do not use it for: builds, tests, linting, deployments and reproducible scripts. GitHub’s repository says to keep conventional Actions for these.
- Cost: the project is MIT licensed and available on GitHub Free, Team and Enterprise. The default engine, Copilot CLI, still needs a Copilot license, and runner resources and engine usage cost extra.
- Safety: agents are read-only and sandboxed by default. GitHub still asks for careful human supervision.
A rule of thumb: script or agent?
Ask one question. Can you write every step down in advance? If yes, write a script. If the job needs someone to read, interpret and decide, use an agent.
| Task | Better fit | Why |
|---|---|---|
| Build, test, lint, deploy | Conventional Actions | The result should be the same every run |
| Reproducible scripts | Conventional Actions | No interpretation required |
| Triage new issues | Agentic workflow | Needs reading and interpreting text |
| Investigate a failing CI run | Agentic workflow | Needs reasoning about logs and causes |
| Keep documentation current | Agentic workflow | Needs understanding of code changes |
The repository says it in one line: Agentic Workflows complement existing CI/CD and do not replace it. Think of the agent as a teammate beside your pipeline, not a new pipeline.
How an agentic workflow is built
A workflow file has two parts. The YAML frontmatter sets triggers, permissions, tools and the AI engine. The Markdown body tells the agent what to accomplish. Running gh aw compile validates the file and generates a .lock.yml file that Actions executes.
The result is a normal Actions workflow. It runs on your existing runner groups and follows your existing policy constraints. You can power each workflow with GitHub Copilot or your own coding agent. The repository lists GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini and Pi.
What to start with
The repository names six task types that fit well: issue triage, pull-request review, CI failure investigation, documentation maintenance, dependency analysis and repository reporting. GitHub does not name one starter workflow. Our suggestion is issue triage or CI failure investigation, because both only read and report.
- Install the extension with gh extension install github/gh-aw.
- Follow the quickstart. You pick an engine, add a sample workflow and run it through Actions.
- Browse the agentics repository from GitHub Next for prebuilt workflows covering triage, dependency management, code review and reporting.
- Review the permissions, tools and network access before you turn it on for the whole team.
The three cost layers
Being on your plan does not make the agent free. The announcement names three separate layers.
- License: the default Copilot CLI engine requires a Copilot license. Other engines have their own terms.
- Resources: the workflow still runs on Actions runners.
- Engine usage: the agent’s AI usage counts toward the estimate.
GitHub lists no prices. Use gh aw forecast to plan. It is no longer experimental, and it now includes threat detection credits and monthly ranges for AI credit spend.
The security posture in plain words
The agent starts with the least power. It reads. It does not write. It runs in a sandboxed container behind the Agent Workflow Firewall and follows integrity filter rules when it reads GitHub content.
When it wants to change something, the request goes through safe outputs. Write actions are buffered, validated and applied in separate jobs with scoped permissions. A dedicated threat detection job scans proposed changes before they are applied.
These controls are configurable. That means you own the review: check permissions, tools, network access and generated files before deployment. The repository adds that you should use the project with caution and at your own risk.
One version warning. Security advisory GHSA-8h78-hpm7-29gg affected versions from 0.83.3 up to, but not including, 0.85.4. GitHub retired those releases as a pre-emptive measure. Do not pin them.
What is new since the public preview
- Workflows can run on self-hosted Actions Runner Controller runners with Docker-in-Docker.
- The model inventory was refreshed, providers can be chosen per workflow, and gh aw add-wizard adds new templates.
- A router can pick a model by task type and difficulty.
- Agents can run in a Cloud Hypervisor or NVX micro-VM, and enclaves aim to prevent data leaks in cross-repository workflows.
Questions and answers
Are Agentic Workflows free?
The software is MIT licensed, but running an agent is not free. The default engine needs a Copilot license, and runner resources and engine usage add cost.
Do they replace my CI?
No. GitHub says they complement CI/CD. Builds, tests and deployments should stay in conventional Actions.
Can an agent change my code on its own?
Not by default. Agents are read-only. Allowed writes pass through validated safe-outputs jobs with scoped permissions, and a threat detection job scans proposed changes first.
Which AI engines can run them?
Copilot by default, or your own coding agent. The repository lists GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini and Pi.
What does gh aw compile do?
It validates your Markdown workflow and generates a .lock.yml file. Actions then executes that file like any other workflow.
Terms in plain language
- GitHub Actions: GitHub’s built-in system for running automated jobs in a repository.
- Triage: sort and prioritize incoming issues.
- Sandbox: an isolated space where code cannot touch the rest of the system freely.
- Safe outputs: a step that checks an agent’s proposed writes before they are applied.
- Runner: the machine that executes an Actions job.
Sources
- GitHub changelog: GitHub Agentic Workflows generally available (October 28, 2026)
- GitHub repository: github/gh-aw
This guide summarizes the two pages above. We did not install the CLI or run a workflow.
Facts read on 29 October 2026
