GitHub Agentic Workflows: Write CI Automation in Markdown, Run It as an AI Agent

GitHub has released gh-aw (GitHub Agentic Workflows), an MIT-licensed CLI extension that lets developers write CI automation in Markdown and run it as an AI agent using GitHub Copilot, Claude, OpenAI Codex, or Google Gemini, compiling to standard GitHub Actions YAML. The tool, which has over 4,800 stars, defaults to read-only operations with sandboxing and safe-outputs for writes, but GitHub is retiring releases 0.68.4 through 0.71.3 due to a billing bug, urging users to upgrade.

GitHub Agentic Workflows: Write CI Automation in Markdown, Run It as an AI Agent gh-aw GitHub Agentic Workflows is GitHub's own MIT-licensed CLI extension for writing repository automation in plain Markdown that compiles to real GitHub Actions YAML, running Copilot, Claude, Codex, or Gemini as the agent with read-only defaults, sandboxing, and safe-outputs for writes. - ⭐ 4852 - Go - MIT - Updated 2026-08-03 CI/CD Tools Compared: GitHub Actions vs GitLab CI vs Jenkins https://dibi8.com/resources/dev-utils/cicd-tools-github-actions-vs-gitlab-ci-vs-jenkins/ • Agent Governance Toolkit: Microsoft’s Answer to “Which Agent Did This?” https://dibi8.com/resources/llm-frameworks/agent-governance-toolkit-microsoft-2026/ What Is GitHub Agentic Workflows? what-is-github-agentic-workflows GitHub Agentic Workflows gh-aw is GitHub’s own answer to “what if a CI workflow’s steps were an AI agent’s judgment instead of a fixed shell script?” The README’s own framing: “Actions + Agent + Safety.” You write repository automation in plain Markdown — a description of what should happen, plus a YAML frontmatter block for trigger and engine config — and gh-aw runs GitHub Copilot, Claude, OpenAI Codex, or Google Gemini as the agent that carries it out inside GitHub Actions. 🔗 GitHub : https://github.com/github/gh-aw https://github.com/github/gh-aw MIT licensed, built and maintained by GitHub itself, at 4,800+ stars , with a commit from August 2, 2026 — the day before this article. Being a first-party GitHub project not a third-party wrapper around Actions gives it a credibility baseline most agentic-CI tools don’t start with. Worth flagging upfront : the README currently warns that releases 0.68.4 through 0.71.3 are being retired due to a bug that impacts billing — if you’re already running gh-aw, check your version and upgrade gh extension upgrade aw before relying on it further. Installation & Quick Start installation--quick-start curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash No GitHub token is required for the install script itself. Then, inside a repository: gh aw init init configures the repository for agentic workflows — this is a one-time setup step per repo, separate from creating an individual workflow. Create a new workflow gh aw new <workflow-name Compile the Markdown workflow into a real Actions .lock.yml gh aw compile workflow-name Debug a workflow run gh aw logs workflow-name gh aw audit <run-id Validate and auto-fix compiled workflows gh aw fix --write gh aw compile --validate How It Actually Runs: Markdown In, .lock.yml Out how-it-actually-runs-markdown-in-lockyml-out This is the architectural detail that matters most: a gh-aw workflow is not directly executable . You author .github/workflows/<name .md Markdown body + YAML frontmatter , and gh aw compile generates a companion .github/workflows/<name .lock.yml — a real, standard GitHub Actions workflow file — which is what GitHub Actions actually runs. The docs recommend marking the generated file in .gitattributes : .github/workflows/ .lock.yml linguist-generated=true merge=ours So the Markdown file is the human-editable source of truth, and the .lock.yml is a build artifact you commit alongside it — conceptually similar to committing a lockfile next to a manifest. Choosing an Engine choosing-an-engine Pick whichever AI account you already have — each engine needs its own credential wired in as a repo secret or permission: | Engine | What you configure | |---|---| GitHub Copilot | copilot-requests: write permission | Claude Anthropic | ANTHROPIC API KEY repository secret | OpenAI Codex | OPENAI API KEY repository secret | Google Gemini | GEMINI API KEY repository secret | Custom engine | Documented separately for non-built-in engines | Guardrails: Read-Only by Default guardrails-read-only-by-default The project’s Guardrails section is unusually direct for a first-party tool, and worth quoting rather than paraphrasing: Read-only permissions by default — write operations are only allowed through sanitized “safe outputs” , not raw agent write access Sandboxed execution and network isolation Input sanitization Supply-chain security — SHA-pinned dependencies Tool allow-listing and compile-time validation Access gating to team members only, with human approval gates for critical operations And the project’s own bottom line: “Using agentic workflows in your repository requires careful attention to security considerations and careful human supervision, and even then things can still go wrong. Use it with caution, and at your own risk.” That’s not boilerplate — it’s the same maintainer team telling you not to fully trust the guardrails either. Key Features, at a Glance key-features-at-a-glance Natural Language Workflows — Markdown + YAML frontmatter instead of hand-written Actions YAML Multi-engine support — Copilot, Claude, Codex, Gemini, or a custom engine MCP server integration — connect Model Context Protocol servers for additional tools inside a workflow Safe Outputs — structured, sanitized communication channel between the AI and the GitHub API Strict Mode — security-first validation and sandboxing Shared Components — reusable workflow building blocks across repos Repo Memory — persistent, git-backed storage so an agent can retain context across separate runs gh-aw vs. Hand-Written GitHub Actions gh-aw-vs-hand-written-github-actions | Aspect | gh-aw | Hand-written Actions YAML | |---|---|---| Authoring format | Markdown + YAML frontmatter | Raw YAML | What executes the logic | An AI agent Copilot/Claude/Codex/Gemini | Fixed shell commands / actions | Adapts to unexpected repo state | Yes — agent reasons about context | No — script does exactly what’s written | Write permissions | Read-only by default, writes via safe-outputs | Whatever the workflow’s permissions: block grants | Compiled artifact | .md source → .lock.yml generated | YAML is already the final artifact | Best fit | Judgment-requiring, variable tasks triage, summarization, review | Deterministic, well-defined build/test/deploy steps | Use Cases use-cases 1. Daily Repository Status Summaries 1-daily-repository-status-summaries The README’s own quick-start example: a scheduled workflow that summarizes open issues, recent PRs, and CI health — the kind of task that benefits from an agent synthesizing varied signals rather than a fixed report template. 2. Issue Triage and Labeling 2-issue-triage-and-labeling An agent reading a new issue’s content and context to apply labels or route it, rather than keyword-matching rules that miss nuance. 3. PR Review Assistance Inside CI 3-pr-review-assistance-inside-ci Running an agent against a PR diff for a first-pass review comment, gated behind read-only permissions and safe-outputs so it can comment but not merge or push unreviewed changes. 4. Repository Maintenance Tasks That Need Judgment 4-repository-maintenance-tasks-that-need-judgment Tasks like “check if this dependency bump is safe to auto-merge” benefit from an agent that can read changelogs and test output, versus a purely rule-based bot. Related Repositories related-repositories | Repository | Purpose | |---|---| | Related Articles related-articles CI/CD Tools Compared: GitHub Actions vs GitLab CI vs Jenkins https://dibi8.com/resources/dev-utils/cicd-tools-github-actions-vs-gitlab-ci-vs-jenkins/ — for the underlying CI platform gh-aw builds on top of Agent Governance Toolkit: Microsoft’s Answer to “Which Agent Did This?” https://dibi8.com/resources/llm-frameworks/agent-governance-toolkit-microsoft-2026/ — a complementary governance layer for agents operating outside the CI-specific guardrails gh-aw already ships Conclusion conclusion GitHub Agentic Workflows is GitHub’s own bet that a meaningful slice of CI automation is better expressed as “an agent that understands the task” than as “a script that handles the cases we thought of.” The Markdown-to- .lock.yml compilation model keeps workflows readable and diffable, the multi-engine support avoids vendor lock-in to one AI provider, and the Guardrails section is refreshingly candid that read-only defaults and safe-outputs reduce risk without eliminating it. The active billing-bug warning for a specific version range is also worth taking as a sign of a fast-moving, not-yet-fully-settled project — check your version before depending on it in production CI. Best for : Teams already on GitHub Actions who want judgment-requiring automation triage, summarization, first-pass review handled by an AI agent, with GitHub’s own guardrails rather than a third-party wrapper. GitHub : https://github.com/github/gh-aw https://github.com/github/gh-aw Last updated: 2026-08-03