Playbooks · Coding tasks
Run a reasoning task on a schedule with GitHub Agentic Workflows: one Markdown file, one reviewed pull request
Written November 1, 2026
For a maintainer who wants issue triage, CI-failure investigation, or documentation updates done by an agent on a trigger: GitHub Agentic Workflows became generally available on 28 October 2026. Write the task as a Markdown file, compile it into a standard Actions workflow, and start with the agent reading only — changes land as a pull request a person reviews.
What changed
GitHub Agentic Workflows, an open source project from GitHub Next, is now generally available on github.com for GitHub Free, Team, and Enterprise. You define an automation in a natural-language Markdown file, and the tool compiles it into standard Actions YAML, so it reuses your existing runner groups and policy constraints. The agent runs inside GitHub Actions, powered by the GitHub Copilot CLI by default, or by a coding agent you bring: Claude Code, OpenAI Codex, Google Gemini, or Pi. Using the default Copilot CLI engine requires a Copilot licence. The new release adds Actions Runner Controller with Docker-in-Docker support, per-workflow model providers with a model router, Cloud Hypervisor or NVX micro-VM isolation with enclaves for cross-repository work, and a forecast command that is no longer experimental and now includes threat-detection credits and monthly ranges.
GitHub describes layered safeguards for these workflows. Agents access GitHub content respecting integrity-filter rules, run with read-only permissions by default, and execute inside a sandboxed container behind the Agent Workflow Firewall. Outputs are validated through a safe-outputs process, and a dedicated threat-detection job scans proposed changes before they are applied. The documentation puts the same point more plainly: agents read by default, and every write must pass a check before it lands. That default is the starting point for the workflow below — do not grant write access in the first version.
Before you start
Pick a repository where you have write access, with GitHub Actions enabled, and one low-stakes task: a daily status report, issue triage labels, or a documentation check. The quickstart guide asks for the GitHub CLI version 2.0.0 or newer, a login with the repo and workflow scopes, and an account for the engine you plan to use — Copilot, Anthropic, OpenAI, or Google. Before enabling the workflow, read the selected engine's data-handling and setup requirements, and judge whether the repository's contents are suitable for an agent run with log and artifact access. Each engine authenticates its own way: Copilot through organization billing or a COPILOT_GITHUB_TOKEN secret, Claude Code through an ANTHROPIC_API_KEY secret or workload identity federation, Codex through an OPENAI_API_KEY secret, and Gemini through a GEMINI_API_KEY secret or workload identity federation. A Claude subscription token from claude login is not supported, and the CLI fails with an error naming the supported alternatives.
Steps
- Install the extension. From any directory, run:
gh extension install github/gh-aw - Add the sample workflow through the wizard. From your repository root, run:
The wizard checks prerequisites, asks you to select an AI engine, configures that engine's authentication, and adds the workflow file and its generated Actions lock file togh aw add-wizard githubnext/agentics/repo-status.github/workflows/, by direct push or by pull request. Choose the pull-request route. The sample workflow gathers recent repository activity — issues, pull requests, discussions, releases, and code changes — and opens a GitHub issue summarizing it. Read the Markdown file it adds before the first run, and confirm the task it describes is the task you want. - Forecast the spend before enabling a schedule. Run the forecast command:
Read its output for the workflow, including threat-detection credits and the monthly range, and decide whether the schedule you plan is worth that spend. GitHub's documentation gives default budget caps of 1,000 AI credits per run and 5,000 per day, with a separate 400-credit default for a threat-detection run. Set lower caps for the first workflow if those defaults are more than the task is worth to you, and treat the forecast as an estimate for your repository's volume, not a fixed price.gh aw forecast - Run it once, read-only, and watch the run. Trigger the first run from the CLI or the Actions tab, and watch it with
gh aw statusorgh run watch. The quickstart guide says an automated run can take two to three minutes. Check the issue it opens against the repository yourself: are the summaries accurate, are the suggested next steps sensible, and did it touch anything it was not asked to touch? If anything in the output surprises you, fix the Markdown task description before the workflow runs on a schedule. - Land changes as a reviewed pull request, never as a direct write. When you move from reports to changes — documentation updates, test additions, small fixes — configure the change as a safe output that creates a pull request, and review that pull request like any other contributor's work: read the diff, run the tests, and merge only what you understand. The threat-detection job scans proposed changes before they apply, but a scan is not a review. If you want to preview outputs without writing anything, GitHub's documentation offers a staged mode that previews every output first.
- Customize the Markdown file, then recompile. Edit the workflow file at
.github/workflows/repo-status.mdto change what the agent includes or how it works. If you changed the frontmatter, the YAML configuration block at the top of the file, regenerate the compiled workflow with:
Commit and push both files, then trigger another run withgh aw compilegh aw run repo-statusand read the new output before trusting the change.
One team's reported results, stated as reported
GitHub's announcement quotes one Accenture team, in the words of Ben Alton, a senior manager on its Strategy, Architecture and Innovation team: one lead saved an estimated 29 hours a week, measured velocity more than doubled on average across the team, AI authored 91 percent of the team's commits, and production errors fell from about 11,000 a day to under 1,000. That is one team's account, quoted by the vendor, for workflows the team built for its own repositories. It is not a general result, and it says nothing about what a first workflow on a different repository will do. Judge your own workflow by the runs you watch in step 4, not by those figures.
What can go wrong
- Granting write access in the first version. A workflow that can open pull requests on its first run can also open wrong ones at machine speed. Start with reports and labels, prove the agent reads the repository correctly, and add write outputs only after a clean run.
- Skipping the forecast on a busy repository. A scheduled workflow on a repository with heavy issue traffic runs far more often than one on a quiet repository. The forecast exists for that difference. Read it before the schedule goes live, not after the first month's usage lands.
- Treating the threat-detection scan as approval. The scan looks for prompt injection, secret leaks, and malicious patches in proposed changes. It does not judge whether a change is correct, wanted, or well written. That judgment stays with the person reviewing the pull request.
- Storing engine credentials the wrong way. Each engine needs its own secret or federation setup, and the quickstart names the exact secret for each. A subscription token where an API key is required fails the run; a key stored anywhere but the repository's secrets stays visible to anyone who can read the workflow file.
Limits
- The safeguards above are GitHub's documented defaults: read-only permissions, a sandboxed container, a firewall, integrity filtering, safe outputs, and threat detection. They limit what the agent can do, not whether its reasoning is right. A read-only agent can still write a wrong report.
- The forecast gives an estimate in AI credits for the workflow as configured. It does not set your bill, and it does not cover runner charges or any separately billed model-provider usage. Read the forecast output for your own repository and engine before enabling a schedule.
- Engine availability and model choice are per workflow, and the engine list here is the quickstart guide's list on the general-availability date. If an engine or model is missing from your installation, the documentation for your installed version governs, not this page.
Related playbooks
- GitHub blocks pull_request_target workflows on December 2
- GitHub Agentic Workflows are now GA
- Lock down agent-built GitHub Actions workflows
- Run your own agent bake-off on one real task
Sources
- https://github.blog/changelog/2026-10-28-github-agentic-workflows-generally-available/
- https://github.github.com/gh-aw/
- https://github.github.com/gh-aw/setup/quick-start/
- https://github.github.com/gh-aw/reference/threat-detection/
Back to: Coding playbooks hub · Also: Triage issues read-only · Review a pull request with a coding agent · Decide whether Copilot's assisted permissions should approve anything for you