gh-aw

GitHub Agentic Workflows

Write agentic workflows in natural language markdown, and run them safely in GitHub Actions. From GitHub Next and Microsoft Research.

[!WARNING] This extension is a research demonstrator. It is in early development and may change significantly. 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.

Quick Start

Ready to get your first agentic workflow running? Follow our step-by-step Quick Start Guide to install the extension, add a sample workflow, and see it in action.

Overview

Learn about the concepts behind agentic workflows, explore available workflow types, and understand how AI can automate your repository tasks. See How It Works.

How It Works

GitHub Agentic Workflows transforms natural language markdown files into GitHub Actions that are executed by AI agents. Here's a simple example:

---
on:
  issues:
    types: [opened]

permissions: read-all 

safe-outputs:
  add-comment:
---

# Issue Clarifier

Analyze the current issue and ask for additional details if the issue is unclear.

The gh aw cli converts this into a GitHub Actions Workflow (.yml) that runs an AI agent (Copilot, Claude, Codex, ...) in a containerized environment whenever a new issue is opened in the repository.

The AI agent reads your repository context, understands the issue content, and takes appropriate actions - all defined in natural language rather than complex code.

Security Benefits: Workflows use read-only permissions by default, with write operations only allowed through sanitized safe-outputs. Access can be gated to team members only, ensuring AI agents operate within controlled boundaries.

Spec-Kit Integration

This repository uses spec-kit for spec-driven development. Spec-kit enables writing specifications that become executable, guiding implementation through a structured workflow:

• Constitution: Project principles and development guidelines in .specify/memory/constitution.md
• Specifications: Feature requirements and user stories created with /speckit.specify
• Plans: Technical implementation approaches with /speckit.plan
• Tasks: Actionable task breakdowns with /speckit.tasks
• Implementation: Automated execution via the spec-kit-executor workflow

The spec-kit-executor workflow runs daily at 8am UTC, scanning for pending tasks and implementing them automatically. See .specify/README.md for details on using spec-kit with this repository.

Documentation

For complete documentation, examples, and guides, see the Documentation.

Contributing

We welcome contributions to GitHub Agentic Workflows! Here's how you can help:

• Report bugs and request features by filing issues in this repository
• Improve documentation by contributing to our docs
• Contribute code by following our Development Guide
• Share ideas in the #continuous-ai channel in the GitHub Next Discord

For development setup and contribution guidelines, see CONTRIBUTING.md.

Share Feedback

We welcome your feedback on GitHub Agentic Workflows! Please file bugs and feature requests as issues in this repository, and share your thoughts in the #continuous-ai channel in the GitHub Next Discord.

Labs

See the Labs page for experimental agentic workflows used by the team to learn, build, and use agentic workflows.