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.

Key Concepts¶

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

Recommended¶

• 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:

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:

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¶

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:

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¶

• gh-aw README
• Quick Start Guide
• Creating Workflows
• Workflow Structure Reference
• Frontmatter Reference
• AI Engines Guide
• Authorization Guide
• Security Architecture

Community¶

• Peli's Agent Factory Blog
• GitHub Discussions

Rhiza-Specific¶

• Integration Plan - Technical implementation details
• Extending Rhiza - Creating custom template bundles
• Quick Reference - Rhiza command reference

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.