// gh-aw CLI usage, compilation, testing, debugging, add-wizard, and CI/CD practices for GitHub Agentic Workflows
| name | agentic-workflow-development |
| description | gh-aw CLI usage, compilation, testing, debugging, add-wizard, and CI/CD practices for GitHub Agentic Workflows |
| license | Apache-2.0 |
Development lifecycle guidance for GitHub Agentic Workflows: CLI setup, compilation, testing, debugging, sharing workflows via add-wizard, version control, and CI/CD integration.
Apply this skill when:
gh aw add-wizardMUST:
gh --version to verifygh extension install github/gh-awgh extension upgrade gh-awgh aw init for new projects.lock.yml)MUST NOT:
.lock.yml filesMUST:
.md files in .github/workflows/gh aw compilegh aw run <workflow-name>.md and .lock.yml files togetherMUST NOT:
.md without .lock.ymlMUST:
gh aw compile --watch for active developmentMUST NOT:
MUST:
workflow_dispatch trigger firstgh aw run <workflow-name> for manual testingMUST NOT:
MUST:
gh aw logs to review execution logsgh aw status to check workflow healthMUST NOT:
MUST:
.md and .lock.yml)MUST NOT:
MUST:
.lock.ymlMUST NOT:
MUST:
MUST NOT:
MUST:
MUST NOT:
MUST:
gh extension upgrade gh-awgh aw upgradeMUST NOT:
# 1. Initialize new repository for agentic workflows
cd my-repo
gh aw init
# 2. Create new workflow file
cat > .github/workflows/issue-triage.md << 'EOF'
---
on: issues
permissions: read-all
tools:
github:
safe-outputs:
create-comment:
max: 1
---
# Issue Triage
Analyze new issues and provide triage information.
EOF
# 3. Start watch mode for development
gh aw compile --watch &
# 4. Edit workflow, save, watch auto-compiles
# (Make changes to issue-triage.md)
# 5. Test workflow manually
gh aw run issue-triage
# 6. Check logs
gh aw logs issue-triage
# 7. Commit both files
git add .github/workflows/issue-triage.md
git add .github/workflows/issue-triage.lock.yml
git commit -m "Add issue triage workflow"
# 8. Push and create PR
git push origin feature/issue-triage
gh pr create --title "Add issue triage workflow" \
--body "Implements automated issue triage with AI"
# Check workflow status
gh aw status
# Review recent logs for specific workflow
gh aw logs my-workflow --tail 100
# Check compilation for errors
gh aw compile --verbose
# Test workflow with debug output
gh aw run my-workflow --debug
# Check GitHub Actions workflow runs
gh run list --workflow=my-workflow.lock.yml
# View specific run logs
gh run view <run-id> --log
# Check for common issues
gh aw doctor
# Create test branch
git checkout -b test/workflow-improvements
# Make changes to workflow
vim .github/workflows/pr-reviewer.md
# Compile and check for errors
gh aw compile
if [ $? -ne 0 ]; then
echo "Compilation failed"
exit 1
fi
# Test workflow (requires PR or issue depending on trigger)
gh aw run pr-reviewer
# Wait and check results
sleep 30
gh aw logs pr-reviewer --tail 50
# If successful, commit
git add .github/workflows/pr-reviewer.md
git add .github/workflows/pr-reviewer.lock.yml
git commit -m "Improve PR reviewer workflow logic"
git push origin test/workflow-improvements
# .github/workflows/workflow-ci.yml
name: Workflow CI
on:
pull_request:
paths:
- '.github/workflows/*.md'
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup GitHub CLI
run: gh --version
- name: Install gh-aw
run: gh extension install github/gh-aw
- name: Compile workflows
run: gh aw compile --check
- name: Validate workflow structure
run: |
for workflow in .github/workflows/*.md; do
echo "Validating $workflow"
gh aw validate "$workflow"
done
- name: Check for security issues
run: gh aw security-check
- name: Verify lock files are up to date
run: |
gh aw compile
if [ -n "$(git status --porcelain .github/workflows/*.lock.yml)" ]; then
echo "Lock files out of date. Run: gh aw compile"
exit 1
fi
---
on: workflow_dispatch
permissions: read-all
tools:
github:
safe-outputs:
create-comment:
max: 1
---
# Debug Example Workflow
**DEBUG MODE ENABLED**
Log all steps for debugging:
1. List repository details
- Log: Repository name, owner, default branch
2. Check issue count
- Log: Total open issues, closed issues
3. Analyze most recent issue
- Log: Issue number, title, author
- Log: Label count, comment count
4. Generate report
- Include all logged data
- Post as comment on issue #1
Use verbose output for all operations.
# Check current gh-aw version
gh extension list
# Upgrade gh-aw extension
gh extension upgrade gh-aw
# Check for workflow upgrades
gh aw check-updates
# Upgrade workflows to latest patterns
gh aw upgrade --dry-run # See what would change
gh aw upgrade # Apply upgrades
# Recompile all workflows
gh aw compile
# Test critical workflows
gh aw run critical-workflow-1
gh aw run critical-workflow-2
# If tests pass, commit
git add .github/workflows/
git commit -m "Upgrade workflows to gh-aw v2.0"
#!/bin/bash
# setup-aw-dev.sh - Set up local environment for agentic workflows
set -e
echo "Setting up Agentic Workflows development environment..."
# Install/update GitHub CLI
if ! command -v gh &> /dev/null; then
echo "Installing GitHub CLI..."
# Installation varies by OS
brew install gh # macOS
fi
# Install gh-aw extension
echo "Installing gh-aw extension..."
gh extension install github/gh-aw || gh extension upgrade gh-aw
# Initialize repository
echo "Initializing repository..."
gh aw init
# Set up git hooks for workflow compilation
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
# Pre-commit hook: Compile workflows
if git diff --cached --name-only | grep -q ".github/workflows/.*\.md"; then
echo "Compiling workflows..."
gh aw compile || exit 1
# Stage updated lock files
git add .github/workflows/*.lock.yml
fi
EOF
chmod +x .git/hooks/pre-commit
echo "Setup complete! Development environment ready."
echo "- gh-aw version: $(gh aw version)"
echo "- Pre-commit hook installed"
#!/bin/bash
# test-workflows.sh - Test all workflows
set -e
echo "Testing all agentic workflows..."
WORKFLOWS=$(ls .github/workflows/*.md | xargs -n1 basename -s .md)
for workflow in $WORKFLOWS; do
echo "Testing: $workflow"
# Compile
gh aw compile "$workflow" || {
echo "❌ Compilation failed: $workflow"
exit 1
}
# Validate structure
gh aw validate "$workflow" || {
echo "❌ Validation failed: $workflow"
exit 1
}
# Security check
gh aw security-check "$workflow" || {
echo "❌ Security check failed: $workflow"
exit 1
}
echo "✅ $workflow passed all checks"
done
echo "All workflows tested successfully!"
# Setup
gh extension install github/gh-aw # Install
gh extension upgrade gh-aw # Update
gh aw init # Initialize repository
# Development
gh aw compile # Compile all workflows
gh aw compile <name> # Compile specific workflow
gh aw compile --watch # Watch mode (auto-recompile)
gh aw compile --check # Validate only (CI)
# Execution
gh aw run <name> # Run workflow manually
gh aw run <name> --debug # Run with debug output
# Monitoring
gh aw logs # All recent logs
gh aw logs <name> # Specific workflow logs
gh aw logs <name> --tail 100 # Last 100 lines
gh aw status # Workflow health
# Sharing
gh aw add <url> # Add workflow from URL
gh aw add-wizard <url> # Add with guided setup
# Diagnostics
gh aw doctor # Diagnose issues
gh aw validate <name> # Validate structure
gh aw security-check # Security audit
# Upgrades
gh aw upgrade # Upgrade workflows
gh aw check-updates # Check for updates
gh aw init.md and .lock.yml committed togethergh aw rungh aw logsgh aw security-checkSymptom: gh aw compile fails
Solutions:
Symptom: Workflow doesn't run on expected events Solutions:
.lock.yml is committedSymptom: Workflow fails with permission errors Solutions:
permissions: in frontmatterSymptom: Workflows take too long or never complete Solutions:
Symptom: AI doesn't follow instructions Solutions:
This skill aligns with:
Development practice violations:
GitHub Agentic Workflows (gh-aw) - markdown-based AI automation with 5-layer security, safe outputs, and Continuous AI patterns
Multi-agent coordination, orchestrator-worker patterns, /plan decomposition, and project coordination for GitHub Agentic Workflows
5-layer defense-in-depth security for GitHub Agentic Workflows - safe outputs, threat detection, AWF firewall, and zero-trust patterns
Continuous AI patterns from Agent Factory - issue triage, documentation sync, code quality, security scanning, and project coordination
GDPR compliance including privacy by design, data protection requirements, consent management, right to be forgotten, and data breach response
Approved cryptographic algorithms, TLS enforcement, key management, and certificate handling per Hack23 Cryptographic Controls Policy