Skip to content

GitHub Agentic Workflows (gh-aw)

This guide explains how to use GitHub Agentic Workflows (gh-aw) in Rhiza-based projects for AI-driven repository automation.

Overview

What is gh-aw?

GitHub Agentic Workflows (gh-aw) enables writing AI-driven automation in natural language Markdown, compiled into GitHub Actions workflows. Instead of writing deterministic YAML steps, you write high-level instructions that an AI agent interprets and executes.

Why use gh-aw with Rhiza?

Rhiza is a living template system that continuously synchronizes configuration into downstream Python projects. Integrating gh-aw into Rhiza means every downstream project can opt in to agentic workflows via a single template bundle, following the same conventions used for CI, Docker, testing, etc.

Traditional Workflow Agentic Workflow
Pre-programmed deterministic steps AI interprets natural language instructions
Fixed logic paths Context-dependent decision making
Brittle (breaks when environment changes) Adaptive (handles unexpected situations)
Written in YAML Written in Markdown with YAML frontmatter

Key Concepts

Concept Description
Workflow files Markdown files (.md) in .github/workflows/ containing YAML frontmatter (triggers, permissions, tools, engine) and natural language instructions
Lock files Compiled GitHub Actions YAML (.lock.yml) generated by gh aw compile
Engines AI coding agents — Copilot (default), Claude, or Codex — that interpret the natural language instructions
Safe outputs Pre-approved write actions (create issues, post comments, open PRs) that bypass the need for direct write permissions
Safe inputs Custom inline MCP tools defined in frontmatter for controlled secret access
Sandbox Agent Workflow Firewall (AWF) — mandatory network egress controls, tool allowlists, and input sanitization

Prerequisites

Required

  1. Git: For version control

  2. GitHub CLI (gh): Version 2.0.0 or later 

    # Check if installed
gh --version

# Install if needed (macOS)
brew install gh

# Install if needed (Linux)
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

  3. GitHub authentication: Logged in with gh auth login

  • AI Engine Access: At least one of:
  • GitHub Copilot subscription (for Copilot engine)
  • Anthropic API key (for Claude engine)
  • OpenAI API key (for Codex engine)

Quick Start

1. Install gh-aw Extension

make install-gh-aw

This installs the gh-aw extension if not already present.

2. Initialize Repository

make gh-aw-init

This sets up the repository for gh-aw by adding: - VS Code settings for workflow editing - Prompt templates - Configuration files

3. Configure Secrets

make gh-aw-setup

This guides you through configuring secrets for your chosen AI engine.

4. Compile Workflows

make gh-aw-compile

This compiles all .md workflow files to .lock.yml files that GitHub Actions can execute.

5. Verify Setup

make gh-aw-status

This shows the status of all agentic workflows in your repository.

Make Targets Reference

All gh-aw functionality is available via make targets:

Command Description
make install-gh-aw Install the gh-aw CLI extension
make gh-aw-init Initialize repository for gh-aw (adds VS Code settings, prompts)
make gh-aw-setup Guided setup for secrets and engine configuration
make gh-aw-compile Compile all agentic workflow .md files to .lock.yml
make gh-aw-compile-strict Compile with strict security validation
make gh-aw-validate Validate that lock files are up-to-date
make gh-aw-status Show status of all agentic workflows
make gh-aw-run WORKFLOW=<name> Run a specific agentic workflow locally
make gh-aw-secrets Bootstrap/check gh-aw secrets
make gh-aw-logs Show logs for recent agentic workflow runs

Starter Workflows

Rhiza provides three pre-configured agentic workflows:

1. Daily Repository Status Report

File: .github/workflows/daily-repo-status.md

Trigger: Weekdays at 09:00 UTC (configurable via cron)

What it does: - Analyzes repository state (issues, PRs, CI status, releases) - Generates a concise status report - Creates an issue with the report

Useful for: Keeping maintainers informed of project health without manual checking.

2. CI Doctor

File: .github/workflows/ci-doctor.md

Trigger: When any CI workflow fails on the main branch

What it does: - Identifies which workflow failed and on which commit - Reads workflow logs to diagnose the failure - Classifies the failure type (test, lint, dependency, infrastructure) - Suggests concrete fixes - Creates an issue with diagnosis and recommended solution

Useful for: Automatically triaging CI failures and reducing time to fix.

3. Issue Triage

File: .github/workflows/issue-triage.md

Trigger: When a new issue is opened

What it does: - Reads issue title and body - Classifies issue type (bug, enhancement, question, documentation) - Applies appropriate labels - Posts a helpful initial comment

Useful for: Automatically categorizing issues and providing immediate feedback to contributors.

Creating Custom Workflows

Workflow Structure

An agentic workflow consists of:

  1. YAML Frontmatter: Configuration (triggers, permissions, tools, engine)
  2. Natural Language Instructions: What you want the AI to do

Example:

---
on:
  schedule:
    - cron: "0 9 * * 1-5"
  workflow_dispatch:

description: "Daily status report for the repository"

engine: copilot

permissions:
  issues: read
  contents: read
  pull-requests: read

tools:
  github:
    toolsets: [repos, issues, pull_requests]

safe-outputs:
  create-issue:
    title: "Daily Status Report — {{ date }}"
    labels: ["report", "automated"]

network:
  allowed:
    - defaults
    - python
---

# Daily Repository Status Report

Analyze the current state of this repository and produce a concise status report.

## What to include

- **Open issues**: Count and highlight any critical/blocking issues
- **Open PRs**: Count, age, and any stale PRs (>7 days without activity)
- **Recent CI status**: Summary of recent workflow runs (pass/fail trends)

## Style

- Be concise and factual
- Use tables where appropriate
- Max 500 words

## Process

1. Read repository metadata, issues, and PRs
2. Check recent workflow run status
3. Compile findings into a structured report
4. Create an issue with the report

Workflow Best Practices

  1. Be Specific: Provide clear, detailed instructions. The more specific you are, the better results you'll get.

  2. Use Constraints: Set limits (word count, execution time, scope) to keep workflows focused.

  3. Provide Context: Include information about the project (Rhiza conventions, key commands, file locations).

  4. Use Safe Outputs: Always use safe-outputs instead of direct write permissions for security.

  5. Test Locally First: Use make gh-aw-run WORKFLOW=<name> to test workflows before committing.

  6. Keep Lock Files in Sync: Always run make gh-aw-compile after editing .md files.

Security Considerations

Guardrails

gh-aw includes multiple layers of security:

Layer Description
Safe Outputs Pre-approved write actions (create issues, comments, PRs) without direct permissions
Network Allowlist Explicit list of allowed domains in network.allowed
Tool Restrictions Only specified tools/toolsets are available to the agent
Permission Scoping Minimal GitHub permissions (read-only by default)
Sandbox Execution Agent Workflow Firewall (AWF) enforces all restrictions
Input Sanitization Automatic sanitization of user inputs to prevent injection
Lock File Validation CI checks ensure .lock.yml matches .md source

Security Best Practices

  1. Minimize Permissions: Only grant permissions the workflow actually needs.

  2. Use Safe Outputs: Prefer safe-outputs over direct write permissions.

  3. Restrict Network: Explicitly list allowed domains in network.allowed.

  4. Review Lock Files: Check .lock.yml changes in PRs to ensure they match .md changes.

  5. Set Timeouts: Use timeout-minutes to prevent runaway workflows.

  6. Role Gating: Use roles: [admin, maintainer] for sensitive workflows.

  7. Never Commit Secrets: Use GitHub secrets, not hardcoded values.

Engine Configuration

Available Engines

Engine Required Secret Best For
Copilot COPILOT_GITHUB_TOKEN GitHub-native tasks, tight integration
Claude ANTHROPIC_API_KEY Complex reasoning, long context
Codex OPENAI_API_KEY Code generation, general tasks

Configuring the Default Engine

In your root Makefile, set:

GH_AW_ENGINE ?= copilot  # or: claude, codex

Per-Workflow Engine Selection

Override the engine in individual workflows via frontmatter:

---
engine: claude  # This workflow uses Claude instead of default
---

Secrets Setup

Interactive Setup

make gh-aw-setup

This will: 1. Prompt you to choose an engine (Copilot/Claude/Codex) 2. Guide you through setting the required secret 3. Run gh aw secrets bootstrap to verify setup 4. Confirm successful configuration

Manual Setup

For Copilot Engine

gh aw secrets set COPILOT_GITHUB_TOKEN
# Enter your GitHub personal access token with Copilot access

For Claude Engine

gh aw secrets set ANTHROPIC_API_KEY
# Enter your Anthropic API key

For Codex Engine

gh aw secrets set OPENAI_API_KEY
# Enter your OpenAI API key

Verifying Secrets

make gh-aw-secrets

This runs gh aw secrets bootstrap to check that all required secrets are configured.

CI/CD Integration

Lock File Validation

The .github/workflows/rhiza_gh-aw-validate.yml workflow automatically validates that:

  1. All .md workflow files are properly formatted
  2. Lock files (.lock.yml) are up-to-date with their source (.md) files
  3. No manual edits have been made to lock files

This runs on: - Pull requests that modify .github/workflows/*.md files - Pushes to main that modify workflow files

Workflow

name: "Validate Agentic Workflows"

on:
  pull_request:
    paths:
      - ".github/workflows/*.md"
  push:
    branches: [main]
    paths:
      - ".github/workflows/*.md"

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install gh CLI
        uses: cli/cli-action@v1

      - name: Install gh-aw extension
        run: gh extension install github/gh-aw
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Validate lock files are up-to-date
        run: |
          gh aw compile
          if ! git diff --quiet .github/workflows/*.lock.yml; then
            echo "::error::Agentic workflow lock files are out of date. Run 'gh aw compile' and commit the changes."
            git diff .github/workflows/*.lock.yml
            exit 1
          fi
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Pre-commit Integration

You can add a pre-commit hook to validate lock files locally:

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: gh-aw-validate
        name: Validate gh-aw lock files
        entry: make gh-aw-validate
        language: system
        pass_filenames: false
        files: '\.github/workflows/.*\.md$'

Troubleshooting

gh-aw Extension Not Found

Problem: gh: 'aw' is not a gh command

Solution: Install the extension: 

make install-gh-aw

Lock Files Out of Date

Problem: CI validation fails with "lock files are out of date"

Solution: Recompile and commit: 

make gh-aw-compile
git add .github/workflows/*.lock.yml
git commit -m "Update gh-aw lock files"

Engine Authentication Failed

Problem: Workflow fails with authentication error

Solution: Verify secrets are configured: 

make gh-aw-secrets
# If missing, run:
make gh-aw-setup

Workflow Not Triggering

Problem: Workflow doesn't run on expected events

Solution: 1. Check that the .lock.yml file exists 2. Verify the trigger conditions in frontmatter 3. Check GitHub Actions logs for errors 4. Ensure required secrets are set

Permission Denied Errors

Problem: Workflow fails with permission denied

Solution: 1. Check permissions: in frontmatter 2. Use safe-outputs instead of direct write permissions 3. Verify GitHub App permissions if using organization

Network Access Blocked

Problem: Workflow can't access external resources

Solution: Add domains to network.allowed in frontmatter: 

network:
  allowed:
    - defaults
    - python
    - "api.example.com"

Rhiza Project Context

Available Commands

When writing workflows for Rhiza-based projects, you can reference these standard commands:

Command Purpose
make test Run pytest with coverage
make fmt Format and lint with ruff
make deptry Check for unused/missing dependencies
uv run pytest Run tests via uv
uv run python <script> Run Python scripts

Project Structure

Rhiza projects follow this structure:

src/          # Source code
tests/        # Tests (pytest)
book/         # Documentation source
.rhiza/       # Rhiza templates and configuration
.github/      # GitHub configuration (including workflows)
pyproject.toml # Project metadata and dependencies

Including Context in Workflows

Example of providing Rhiza context:

---
# ... frontmatter ...
---

# Your Workflow Title

Instructions for the AI agent...

## Project Context

This is a Rhiza-based Python project. Key conventions:
- Dependencies are managed via `uv` and declared in `pyproject.toml`
- Tests use `pytest` and are located in `tests/`
- Code is formatted with `ruff`
- Python version is specified in `.python-version`

## Available Commands

- `make test` — run pytest with coverage
- `make fmt` — format and lint code
- `uv run pytest -v` — run tests with verbose output

Advanced Topics

Custom Safe Outputs

Define custom safe outputs for specific workflow needs:

safe-outputs:
  create-issue:
    title: "{{ workflow_name }}: {{ summary }}"
    labels: ["automated", "{{ severity }}"]
    assignees: ["{{ triggered_by }}"]

  add-comment:
    issue: "{{ issue_number }}"

  create-pr:
    title: "{{ change_description }}"
    branch: "automated/{{ workflow_name }}"
    labels: ["automated"]

Custom Tools

Define custom MCP tools for workflow-specific functionality:

tools:
  github:
    toolsets: [repos, issues, pull_requests]
  bash:
    - "make test"
    - "make fmt"
    - "uv run pytest"
  custom:
    - name: analyze_dependencies
      description: "Analyze project dependencies"
      command: "uv run python scripts/analyze_deps.py"

Multi-Engine Workflows

For complex tasks, you might want different engines for different workflows:

# ci-doctor.md - Uses Claude for complex reasoning
---
engine: claude
---

# ci-failure-triage.md - Uses Copilot for GitHub integration
---
engine: copilot
---

Resources

Official Documentation

Community

Rhiza-Specific

Next Steps

  1. Explore Starter Workflows: Review and run the included workflows to see gh-aw in action
  2. Create Custom Workflows: Adapt the starter workflows or create new ones for your specific needs
  3. Share Knowledge: Document your workflows and share patterns with the team
  4. Monitor Performance: Use make gh-aw-logs to track workflow execution and outcomes
  5. Iterate: Refine workflows based on results and feedback

For questions or issues, please refer to the troubleshooting section or consult the official gh-aw documentation.