README
¶
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.
Contents
- Quick Start
- Overview
- How It Works
- Safe Agentic Workflows
- Documentation
- Contributing
- Share Feedback
- Labs
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 an example:
---
on: daily
permissions: read
safe-outputs:
create-discussion:
---
## Daily Issues Report
Analyze repository issues and create a daily discussion
with metrics, trends, and key insights.
The gh aw cli converts this into a GitHub Actions Workflow (.yml) that runs an AI agent (Copilot, Claude, Codex, ...) in a containerized environment on a schedule or manually.
The AI agent reads your repository context, analyzes issues, generates visualizations, and creates reports - all defined in natural language rather than complex code.
Safe Agentic Workflows
Security is foundational to GitHub Agentic Workflows. Workflows run with read-only permissions by default, with write operations only allowed through sanitized safe-outputs. The system implements multiple layers of protection including sandboxed execution, input sanitization, network isolation, supply chain security (SHA-pinned dependencies), tool allowlisting, and compile-time validation. Access can be gated to team members only, with human approval gates for critical operations, ensuring AI agents operate safely within controlled boundaries. See the Security Guide for comprehensive details on threat modeling, implementation guidelines, and best practices.
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
- Quick Start: See Common Development Tasks for scenario-based command reference
- Share ideas in the
#continuous-aichannel 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.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
awmg
command
|
|
|
gh-aw
command
|
|
|
internal
|
|
|
tools/actions-build
command
|
|
|
tools/generate-action-metadata
command
|
|
|
pkg
|
|
|
cli
Package cli provides batch operations for workflow compilation.
|
Package cli provides batch operations for workflow compilation. |
|
console
Package console provides layout composition helpers for creating styled CLI output with Lipgloss.
|
Package console provides layout composition helpers for creating styled CLI output with Lipgloss. |
|
envutil
Package envutil provides utilities for reading and validating environment variables.
|
Package envutil provides utilities for reading and validating environment variables. |
|
mathutil
Package mathutil provides basic mathematical utility functions.
|
Package mathutil provides basic mathematical utility functions. |
|
repoutil
Package repoutil provides utility functions for working with GitHub repository slugs and URLs.
|
Package repoutil provides utility functions for working with GitHub repository slugs and URLs. |
|
sliceutil
Package sliceutil provides utility functions for working with slices.
|
Package sliceutil provides utility functions for working with slices. |
|
stringutil
Package stringutil provides utility functions for working with strings.
|
Package stringutil provides utility functions for working with strings. |
|
styles
Package styles provides centralized style and color definitions for terminal output.
|
Package styles provides centralized style and color definitions for terminal output. |
|
tty
Package tty provides utilities for TTY (terminal) detection.
|
Package tty provides utilities for TTY (terminal) detection. |
|
workflow
Package workflow provides agent file and feature support validation.
|
Package workflow provides agent file and feature support validation. |