Agentic Workflows integrate AI agents into your automated workflows, allowing you to automate repository tasks which have too much ambiguity to be done programmatically. Instead of needing to write complex YAML following specific syntax, you simply describe what you want done, and an AI agent handles it.
Agentic Workflows allow you to transform natural language from Markdown into automated workflows, incorporating AI agents into your DevOps and RepoOps procedures.
Rather than needing to write out YAML scripts following specific syntax, you simply have to describe what you want done and how, and the AI agent handles it for you.
GitHub's Agentic Workflows is one of the first platform-native implementations of this feature, being built on top of the infrastructure of GitHub Actions.
GitHub Agentic Workflows is currently a research project from GitHub Next and Microsoft Research. Specifications may change, and human supervision is recommended.
GitHub Agentic Workflows consists of a markdown file with frontmatter, describing the triggers, permissions, safe outputs, allowed tools, and more. This is then followed by a set of natural language instructions on what the agent should do.
Currently, you have to use the gh aw CLI extension to compile this to generate the Actions workflow.
This is the current process, but in the future, the development team plans to simplify Agentic Workflows, requiring only a markdown file in .github/workflows to allow “agentic things to just happen”.
For the full specification and guide to setting up your first GitHub Agentic Workflow, check out the GitHub Agentic Workflows documentation.
The key differences are the incorporation of an AI agent and the amount of control you have over your AI agents.
With AI-generated workflows, the agent simply writes the workflow steps into a YAML file, you commit the file, and from then on, it's the same as any other static workflow.
Meanwhile, with regular GitHub Actions that invoke an agent, the YAML file still needs to be written to incorporate AI agents as part of the workflow, which is a pattern that doesn't need to be repeated. Additionally, incorporating AI agents into standard GitHub Actions allow the agent to run with whatever permissions given to the job, without much control over how it achieves its goals - which creates risk.
Where Agentic Workflows really shines is where a bit of “productive ambiguity" helps. For example, a human teammate can understand “read the coverage report and write tests to improve the coverage.” This isn't a programmatic instruction set that needs to be written with GitHub Actions syntax, instead, it's something an AI agent can interpret and execute.
Because an AI agent is making runtime decisions, security becomes critical.
GitHub Agentic Workflows achieve this by inheriting GitHub Actions' sandboxing model, scoped permissions, and auditable execution, enforced by these attributes:
safe-outputsThis is a fundamental difference compared to if you invoked an AI agent in a normal GitHub Action, which runs with whatever permissions you give the job and has no built-in guardrails on what the agent chooses to do.
Agentic Workflows are best suited for repetitive tasks around your RepoOps setup that involve some ambiguity and would benefit from AI reasoning, rather than requiring strict, deterministic outputs. They fit naturally alongside your existing automated workflows, capable of being triggered by the same events that you already use such as code commits, new PRs, etc.
Common use cases for Agentic Workflows include:
Be aware of the scope of what you're using AI for when using Agentic Workflows, as it would increase your AI usage bill, as well as impacting your build/action run minutes on GitHub.
By using a coding agent, you can simply specify your intent with the below prompt, and have the workflow generated in natural language.
Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md{{ YOUR WORKFLOW SPECIFICATION HERE }}
After generating the Markdown file, we recommend giving it a read, and making sure it reflects your original intent.
If you'd prefer to manually create your Agentic Workflows, follow these instructions.
gh aw GitHub CLI extension.md file with YAML frontmatter (triggers, permissions, safe-outputs, tools) followed by natural language instructionsgh aw to generate the GitHub Actions .lock.yml file from your markdown.md source and the generated .lock.yml to your repositoryThe workflow runs on the events you specified, with the AI agent executing your instructions
Learn more at GitHub Agentic Workflow Docs - Manual Editing
You can also create workflows directly through the GitHub web interface using natural language prompts, without needing the CLI.
Here's an example markdown file for an Agentic Workflow that automatically detects and closes duplicate issues.
From there, all you would need to do is compile the workflow markdown into a YAML workflow file using: gh aw compile, producing the YAML file responsible for this workflow.
---description: >Automatically detect duplicate issues and close them with a linkto the original, notifying relevant users.on:issues:types: [opened]permissions:contents: readissues: readpull-requests: readtools:github:toolsets: [default]safe-outputs:add-comment:max: 3close-issue:max: 1update-issue:max: 2noop:max: 1---# Duplicate Issue DetectorYou are an AI agent that detects duplicate issues in this repository.When a new issue is opened, you analyze the existing issue backlog tofind potential duplicates. If a duplicate is found, you close the newissue with a reference to the original and notify relevant users.## Your Task1. **Read the newly opened issue** — get the title, body, and anymentioned users from the triggering issue.2. **Search the issue backlog** — use the GitHub tools to search forexisting open AND closed issues that may cover the same topic.Try multiple search queries to cast a wide net (at least 2-3different queries).3. **Evaluate similarity** — for each candidate, compare titlesimilarity, description overlap, and labels. Look for **semantic**duplicates (same underlying problem described differently).4. **If a duplicate is found**:- Comment on the NEW issue explaining it's a duplicate, linkingto the original with `#<number>`- Close the NEW issue as "not planned"- Comment on the ORIGINAL issue tagging the reporter and anymentioned users for visibility- Add the `duplicate` label to the new issue5. **If NO duplicate is found**:- Call the `noop` safe output with a summary message.## Guidelines- **Be conservative**: Only close if you are confident it is trulya duplicate. When in doubt, leave it open.- **Prefer the older issue**: Always close the newer one.- **Be helpful**: Comments should be polite and explain why youbelieve it's a duplicate.