Do you use GitHub Agentic Workflows?

GitHub Agentic Workflows let you automate repository tasks by writing natural language instructions in markdown. These markdown files then compile into GitHub Actions workflows powered by AI agents. Instead of writing complex YAML, you describe what you want done and an AI agent handles it.

What are GitHub Agentic Workflows?

GitHub Agentic Workflows are a form of natural language programming over GitHub.

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.

An Agentic Workflow file is comprised of five key components:

• Triggers (on:) - the standard GitHub Actions events that would trigger the workflow (e.g. push, schedule, issue opened, etc.)
• Permissions (permissions:) - scoped access controls, defining what the agent has access to. This is read-only by default
• Safe outputs (safe-outputs:) - definition of what an agent is allowed to produce as an output to the Actions workflow (e.g. creating an issue, writing a comment, etc.)
• Tools (tools:) - the operations the agent can use within the process (e.g. edit, web-fetch, etc.)
• Instructions - the natural language section in Markdown where you describe the agent's role, goals, and the steps that it should follow

How is this different from regular AI-generated workflows?

You may be thinking “Why shouldn't I just ask my AI agent to write me a GitHub Action?" The key difference between the two is the amount of control you have over your AI agents!

With AI-generated YAML, the agent writes the workflow steps, you commit the file, and from then on, it's the same as any other static workflow.

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.

Security by design

Because an AI agent is making runtime decisions, security becomes critical. GitHub Agentic Workflows emphasise security by inheriting GitHub Actions' sandboxing model, scoped permissions, and auditable execution, enforced by these attributes:

• Read-only by default - the agent has no write access beyond what is explicitly granted through safe-outputs
• Permission separation - write operations run in separate permission-controlled jobs, and never inside the agentic container itself, preventing AI agents from making write changes beyond what is allowed
• Sandboxed execution - The agent runs in a containerized sandbox within the GitHub Actions VM, with limited filesystem access
• Network isolation - Egress traffic is restricted to a configurable domain allowlist via the Agent Workflow Firewall (AWF)
• Tool allowlisting - Agents can only use pre-approved tools, preventing unauthorized actions

This 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.

When should you use GitHub Agentic Workflows?

Agentic Workflows are best suited for repetitive repository tasks that have a bit of ambiguity and would benefit from AI reasoning, not requiring strict, deterministic outputs.

Common use cases include:

• GitHub Issue triage - Automatically labelling, summarizing, and routing incoming issues
• Documentation updates - Keeping README's and API docs in sync as the code changes with modifications
• Test generation - Analyzing coverage gaps and creating PRs proposing new test cases
• Daily reporting - Generating status reports summarizing recent activity
• Code quality - Suggesting refactoring improvements and filing PRs with fixes

How do you set up GitHub Agentic Workflows?

Option 1: Agentic - Vibe it up! 🤙

1. Prompt your AI Agent to write you an Agentic Workflow with the following prompt:

Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md

{{ YOUR WORKFLOW SPECIFICATION HERE }}

Option 2: Handcraft your prompt 🤓

If you'd prefer to manually create your Agentic Workflows, follow these instructions.

1. Install the gh aw GitHub CLI extension
2. Write a .md file with YAML frontmatter (triggers, permissions, safe-outputs, tools) followed by natural language instructions
3. Run gh aw to generate the GitHub Actions .lock.yml file from your markdown
4. Add both the .md source and the generated .lock.yml to your repository

The workflow runs on the events you specified, with the AI agent executing your instructions

Learn more at GitHub Agentic Workflow Docs - Manual Editing

Example

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 link
  to the original, notifying relevant users.
on:
  issues:
    types: [opened]
permissions:
  contents: read
  issues: read
  pull-requests: read
tools:
  github:
    toolsets: [default]
safe-outputs:
  add-comment:
    max: 3
  close-issue:
    max: 1
  update-issue:
    max: 2
  noop:
    max: 1
---

# Duplicate Issue Detector

You are an AI agent that detects duplicate issues in this repository.
When a new issue is opened, you analyze the existing issue backlog to
find potential duplicates. If a duplicate is found, you close the new
issue with a reference to the original and notify relevant users.

## Your Task

1. **Read the newly opened issue** — get the title, body, and any
   mentioned users from the triggering issue.

2. **Search the issue backlog** — use the GitHub tools to search for
   existing open AND closed issues that may cover the same topic.
   Try multiple search queries to cast a wide net (at least 2-3
   different queries).

3. **Evaluate similarity** — for each candidate, compare title
   similarity, 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, linking
     to the original with `#<number>`
   - Close the NEW issue as "not planned"
   - Comment on the ORIGINAL issue tagging the reporter and any
     mentioned users for visibility
   - Add the `duplicate` label to the new issue

5. **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 truly
  a 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 you
  believe it's a duplicate.

Additional reading

• GitHub Next - Agentic Workflows - The introductory article explaining the vision and design philosophy
• gh-aw Documentation - Official documentation for the CLI extension and workflow format
• Example Workflows - A collection of demonstrator agentic workflows