✨ GitHub Agentic Workflows

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

Caution

This extension is a research demonstrator. It is in early development and may change significantly. It has not been thoroughly tested. Using agentic workflows in your repository requires careful supervision, and even then things can still go wrong. Use it with caution, and at your own risk.

⚡ Quick Start (30 seconds)

Install the extension:

gh extension install githubnext/gh-aw

Now, add a weekly research report to your repo (this adds this sample):

gh aw add weekly-research -r githubnext/agentics --pr

This command will create a PR to your repo adding several files including .github/workflows/weekly-research.md and .github/workflows/weekly-research.lock.yml:

.github/
└── workflows/
  ├── weekly-research.md # Agentic Workflow
  └── weekly-research.lock.yml # Compiled GitHub Actions Workflow

Your repository will also need an ANTHROPIC_API_KEY (for Anthropic Claude) or OPENAI_API_KEY (for OpenAI Codex) Actions secret set up to run workflows that use AI models. You can add this using one of the following commands:

# For Claude engine (default)
gh secret set ANTHROPIC_API_KEY -a actions --body <your-anthropic-api-key>

# For Codex engine (experimental, requires "--engine codex")
gh secret set OPENAI_API_KEY -a actions --body <your-openai-api-key>

Once you've reviewed and merged the PR you're all set! Each week, the workflow will run automatically and create a research report issue in your repository. If you're in a hurry and would like to run the workflow immediately, you can do so using:

gh aw run weekly-research

You can explore other samples at githubnext/agentics. You can also copy those samples and write your own workflows. Any repository that has a "workflows" directory can be used as a source of workflows.

📝 Agentic Workflow Example

Here's what a simple agentic workflow looks like. This example automatically triages new issues:

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

permissions:
  contents: read      # Minimal permissions for main job

tools:
  github:
    allowed: [add_issue_comment]

output:
  issue:
    title-prefix: "[triage] "
    labels: [automation, triage]

timeout_minutes: 5
---

# Issue Triage

Analyze issue #${{ github.event.issue.number }} and help with triage:

1. Read the issue content
2. Post a helpful comment summarizing the issue
3. Write your analysis to ${{ env.GITHUB_AW_OUTPUT }} for automatic issue creation

Keep responses concise and helpful.

💡 Learn more: For complete workflow configuration details, see the Documentation

📚 Workflow commands: See Commands Documentation for complete workflow management commands including list, status, enable, disable, and more.

🤖 Teach AI how write agentic workflows with custom instructions.

📂 Available Demonstrator Workflows from "The Agentics"

Research & Planning Workflows

• 📚 Weekly Research - Collect research updates and industry trends
• 👥 Daily Team Status - Assess repository activity and create status reports
• 📋 Daily Plan - Update planning issues for team coordination
• 🏷️ Issue Triage - Triage issues and pull requests

Coding & Development Workflows

• 📦 Daily Dependency Updater - Update dependencies and create pull requests
• 📖 Regular Documentation Update - Update documentation automatically
• 🔍 Daily QA - Perform quality assurance tasks
• 🔍 Daily Accessibility Review - Review application accessibility

📖 Deep Dive

What's this extension for?

The extension is to support Continuous AI workflows. Continuous AI is a label we've identified for all uses of automated AI to support software collaboration on any platform.

We've chosen the term "Continuous AI” to align with the established concept of Continuous Integration/Continuous Deployment (CI/CD). Just as CI/CD transformed software development by automating integration and deployment, Continuous AI covers the ways in which AI can be used to automate and enhance collaboration workflows.

“Continuous AI” is not a term GitHub owns, nor a technology GitHub builds: it's a term we use to focus our minds, and which we're introducing to the industry. This means Continuous AI is an open-ended set of activities, workloads, examples, recipes, technologies and capabilities; a category, rather than any single tool.

Some examples of Continuous AI are:

• Continuous Documentation: Continually populate and update documentation, offering suggestions for improvements.

• Continuous Code Improvement: Incrementally improve code comments, tests and other aspects of code e.g. ensuring code comments are up-to-date and relevant.

• Continuous Triage: Label, summarize, and respond to issues using natural language.

• Continuous Summarization: Provide up-to-date summarization of content and recent events in the software projects.

• Continuous Fault Analysis: Watch for failed CI runs and offer explanations of them with contextual insights.

• Continuous Quality: Using LLMs to automatically analyze code quality, suggest improvements, and ensure adherence to coding standards.

• Continuous Team Motivation: Turn PRs and other team activity into poetry, zines, podcasts; provide nudges, or celebrate team achievements.

• Continuous Accessibility: Automatically check and improve the accessibility of code and documentation.

• Continuous Research: Automatically research and summarize relevant topics, technologies, and trends to keep the team informed.

So far you've just explored the Continuous Research example, but you can write your own workflows to explore all the others! Further samples are available at githubnext/agentics.

What are lock files?

Adding an agentic workflow adds two main files, for example:

• .github/workflows/weekly-research.md
• .github/workflows/weekly-research.lock.yml

Both files are stored in .github/workflows/ - the first file is the markdown file that defines the workflow, and the second is a lock file that contains the resolved workflow configuration to an actual GitHub Actions workflow.

Updating after workflow edits

You are in control of the workflow files in .github/workflows/ and can adapt them to your needs. If you modify the markdown file, you can compile it to update the lock file:

gh aw compile

You will see the changes reflected in the .lock.yml file, which is the actual workflow that will run on GitHub Actions. You should commit changes to both files to your repository.

Configuring the agentic processor

By default Claude Code is used as the agentic processor. You can configure the agentic processor by editing the frontmatter of the markdown workflow files.

engine: claude  # Default: Claude Code
engine: codex   # Experimental: OpenAI Codex CLI with MCP support

You can also specify this on the command line when adding or running workflows:

# Use Claude (default)
gh aw add weekly-research --engine claude

# Use Codex (experimental)
gh aw add weekly-research --engine codex

This will override the engine setting in the frontmatter of the markdown file.

🔧 Advanced configuration: For detailed information about permissions, tools, secrets, and all configuration options, see the Documentation

Security of Agentic Workflows

Security is a key consideration when using agentic workflows. Please see the Security Notes for guidelines related to workflow security and handling untrusted inputs.

Caution

GitHub Agentic Workflows is a research demonstrator, and Agentic Workflows are not for production use.

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

🔗 Related Projects

• Continuous AI
• GitHub Actions
• GitHub CLI
• Model Context Protocol