GitHub Agentic Workflows

Skill by ara.so — AI Agent Skills collection.

GitHub Agentic Workflows (gh-aw) is a framework for creating AI-powered automation workflows that can autonomously maintain repositories, review code, triage issues, update documentation, and perform developer tasks. Workflows are defined in simple Markdown files and run as GitHub Actions.

What It Does

Autonomous Repository Maintenance: AI agents that triage issues, label PRs, fix bugs, and maintain documentation
Code Review: Automated PR reviews with configurable personas (grumpy reviewer, nitpick reviewer, etc.)
CI/CD Intelligence: Monitor and diagnose CI failures, optimize workflows, track costs
Documentation: Auto-update docs, maintain wikis, check links, generate glossaries
Planning & Reporting: Generate status reports, research summaries, activity chronicles
Security: Scan for malicious code, generate VEX statements for security alerts

Installation

Prerequisites

GitHub repository with Actions enabled
GitHub App or Personal Access Token with appropriate permissions
Access to an AI model provider (OpenAI, Anthropic, etc.)

Basic Setup

Install the
```
gh-aw
```
CLI:

bash

# Using npm
npm install -g @github/gh-aw

# Or using GitHub CLI extension
gh extension install github/gh-aw

Create
```
.github/workflows
```
directory in your repository:

bash

mkdir -p .github/workflows

Copy a workflow from the Agentics collection:

bash

# Example: Issue Triage workflow
curl -o .github/workflows/issue-triage.yml \
  https://raw.githubusercontent.com/githubnext/agentics/main/.github/workflows/issue-triage.yml

curl -o .github/workflows/issue-triage.md \
  https://raw.githubusercontent.com/githubnext/agentics/main/workflows/issue-triage.md

Configure secrets in your repository settings:
- ```
GITHUB_TOKEN
```
  (automatically available)
- ```
OPENAI_API_KEY
```
  or
```
ANTHROPIC_API_KEY
```
  (for AI model access)

Workflow Structure

Agentic workflows consist of two files:

YAML file (
```
.github/workflows/*.yml
```
) - GitHub Actions configuration
Markdown file (
```
.github/workflows/*.md
```
) - Agent instructions and behavior

Example: Issue Triage Workflow

.github/workflows/issue-triage.yml
:

yaml

name: Issue Triage
on:
  issues:
    types: [opened, edited]
  pull_request:
    types: [opened, edited]

jobs:
  triage:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: github/gh-aw@v1
        with:
          workflow: .github/workflows/issue-triage.md
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

.github/workflows/issue-triage.md
:

markdown

# Issue Triage Agent

You are a helpful issue triage assistant. When a new issue or pull request is opened:

1. Read the title and body carefully
2. Analyze the content to determine appropriate labels
3. Apply relevant labels from the repository's label set
4. Add a welcoming comment if this is a first-time contributor

## Available Tools

- `github.issues.addLabels` - Add labels to issues
- `github.issues.createComment` - Comment on issues
- `github.pulls.requestReviewers` - Request reviewers for PRs

## Labels to Consider

- `bug` - Something isn't working
- `enhancement` - New feature or request
- `documentation` - Documentation improvements
- `good first issue` - Good for newcomers
- `help wanted` - Extra attention needed

## Example Analysis

For a bug report mentioning crashes, apply: `bug`, potentially `help wanted`
For a feature request, apply: `enhancement`
For documentation fixes, apply: `documentation`, potentially `good first issue`

Key Workflow Types

Maintainer Workflows

Repo Assist - Comprehensive repository assistant:

yaml

name: Repo Assist
on:
  schedule:
    - cron: '0 */6 * * *'  # Every 6 hours
  issues:
    types: [opened, edited, labeled]
  pull_request:
    types: [opened, edited, synchronize]

jobs:
  assist:
    runs-on: ubuntu-latest
    steps:
      - uses: github/gh-aw@v1
        with:
          workflow: .github/workflows/repo-assist.md
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Code Review Workflows

Grumpy Reviewer - On-demand opinionated reviews:

yaml

name: Grumpy Reviewer
on:
  issue_comment:
    types: [created]

jobs:
  review:
    if: contains(github.event.comment.body, '/grumpy-review')
    runs-on: ubuntu-latest
    steps:
      - uses: github/gh-aw@v1
        with:
          workflow: .github/workflows/grumpy-reviewer.md

Documentation Workflows

Daily Doc Updater:

yaml

name: Documentation Updater
on:
  schedule:
    - cron: '0 9 * * *'  # Daily at 9 AM
  workflow_dispatch:

jobs:
  update-docs:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: github/gh-aw@v1
        with:
          workflow: .github/workflows/doc-updater.md

Custom Workflow Creation

Basic Template

markdown

# My Custom Agent

## Role
You are a [describe the agent's role and purpose].

## Triggers
This workflow runs when [describe trigger conditions].

## Tasks

1. [First task description]
2. [Second task description]
3. [Third task description]

## Available Tools

List the GitHub API tools you'll use:
- `github.issues.create` - Create new issues
- `github.repos.createOrUpdateFileContents` - Update files
- `github.pulls.create` - Create pull requests

## Guidelines

- [Guideline 1]
- [Guideline 2]
- [Guideline 3]

## Output Format

Provide results as:
- Summary of actions taken
- Links to created issues/PRs
- Any recommendations

Using Shared Fragments

Import reusable components:

markdown

# My Workflow

imports: [shared/formatting.md, shared/arxiv.md]

## Tasks

Use the arXiv MCP server to search for relevant papers on [topic].
Format the output using the standard formatting guidelines.

Advanced: MCP Server Integration

markdown

# Research Assistant

imports: [shared/arxiv.md, shared/markitdown.md]

## Tasks

1. Search arXiv for papers on "machine learning optimization"
2. Download the top 3 papers as PDFs
3. Convert PDFs to Markdown using MarkItDown
4. Summarize findings in an issue

## MCP Servers

- **arxiv**: Search and retrieve academic papers
- **markitdown**: Convert PDFs to readable Markdown

Configuration

Environment Variables

Set in repository secrets or

.env

bash

# Required
GITHUB_TOKEN=ghp_your_token_here
OPENAI_API_KEY=sk-your-key-here

# Optional - Alternative AI providers
ANTHROPIC_API_KEY=sk-ant-your-key-here
AZURE_OPENAI_API_KEY=your-azure-key-here
AZURE_OPENAI_ENDPOINT=https://your-endpoint.openai.azure.com

# Optional - Cost tracking
GH_AW_ENABLE_COST_TRACKING=true

Workflow Permissions

Required permissions in workflow YAML:

yaml

permissions:
  contents: write        # To create/update files
  issues: write          # To manage issues
  pull-requests: write   # To manage PRs
  discussions: write     # To manage discussions (if needed)

Common Patterns

Command-Triggered Workflows

Allow users to trigger agents via comments:

yaml

on:
  issue_comment:
    types: [created]

jobs:
  command-handler:
    if: |
      contains(github.event.comment.body, '/plan') ||
      contains(github.event.comment.body, '/fix')
    runs-on: ubuntu-latest
    steps:
      - uses: github/gh-aw@v1
        with:
          workflow: .github/workflows/commands.md

Scheduled Maintenance

Run workflows on a schedule:

yaml

on:
  schedule:
    - cron: '0 0 * * 1'  # Weekly on Monday
    - cron: '0 9 * * *'  # Daily at 9 AM
    - cron: '0 */6 * * *'  # Every 6 hours

Multi-Stage Workflows

Chain multiple agents together:

markdown

# Multi-Stage Pipeline

## Stage 1: Analysis
Analyze the repository for issues.

## Stage 2: Planning
Create a plan to address the issues.

## Stage 3: Execution
Implement the plan and create PRs.

## Stage 4: Verification
Verify the changes and update status.

Conditional Execution

markdown

# Conditional Agent

## Pre-Check

Before proceeding, verify:
- There are open issues labeled "needs-triage"
- No other triage workflow is currently running
- The repository has been active in the last 7 days

If conditions aren't met, exit gracefully.

## Main Task

[Rest of workflow...]

Real-World Examples

Example 1: Bug Fix Automation

markdown

# Bug Fix Agent

## Role
You are an experienced developer who investigates and fixes bugs.

## Workflow

1. **Identify**: Find issues labeled "bug" that haven't been updated in 3 days
2. **Investigate**: 
   - Read the issue description
   - Check related code files
   - Review recent commits that might be related
   - Look for similar closed issues
3. **Diagnose**: Determine the root cause
4. **Fix**: 
   - Create a branch named `fix/issue-{number}`
   - Implement the fix
   - Write or update tests
   - Commit changes with descriptive message
5. **PR**: Create a pull request referencing the issue
6. **Update**: Comment on the original issue with findings and PR link

## Tools

- `github.search.issuesAndPullRequests` - Find bugs
- `github.repos.getContent` - Read code files
- `github.git.createRef` - Create branch
- `github.repos.createOrUpdateFileContents` - Update files
- `github.pulls.create` - Create PR
- `github.issues.createComment` - Update issue

## Quality Standards

- All fixes must include tests
- Code must follow existing style conventions
- Commit messages must be descriptive
- PRs must reference the issue number

Example 2: Documentation Sync

markdown

# Documentation Synchronizer

imports: [shared/formatting.md]

## Role
Keep documentation in sync with code changes.

## Workflow

1. **Detect Changes**: 
   - Find files changed in the last 24 hours
   - Filter for source code files (.js, .py, .go, etc.)
   - Identify public APIs or functions modified

2. **Check Documentation**:
   - Locate corresponding documentation files
   - Compare documented behavior with actual code
   - Identify discrepancies

3. **Update Documentation**:
   - Create branch `docs/auto-sync-{date}`
   - Update affected documentation files
   - Add examples if new features were added
   - Update any code snippets

4. **Create PR**:
   - Title: "docs: sync with code changes from {date}"
   - Body: List all changes with links to commits
   - Request review from code authors

## File Mappings

- `src/api/*.js` → `docs/api/*.md`
- `src/cli/*.js` → `docs/cli-reference.md`
- `lib/*.py` → `docs/library-reference.md`

## Output Format

Use the standard formatting from shared/formatting.md

Example 3: CI Cost Optimizer

markdown

# CI Cost Optimizer

imports: [shared/reporting.md]

## Role
Monitor and optimize CI/CD costs.

## Analysis Tasks

1. **Collect Data**:
   - Get all workflow runs from the past 7 days
   - Calculate total execution time per workflow
   - Identify slowest steps in each workflow

2. **Identify Waste**:
   - Find workflows with high failure rates
   - Detect redundant test runs
   - Spot overly aggressive schedule triggers
   - Find unnecessarily large runners

3. **Generate Report**:
   - Calculate estimated costs (if applicable)
   - Create visualization of run times
   - Highlight optimization opportunities
   - Provide specific recommendations

4. **Create Issue**:
   - Title: "CI Optimization Report - Week {number}"
   - Include all findings and recommendations
   - Tag with "ci", "optimization", "cost-savings"

## Cost Calculations

- Small runner: ~$0.008/minute
- Medium runner: ~$0.016/minute
- Large runner: ~$0.032/minute

## Optimization Checks

- [ ] Are tests running in parallel where possible?
- [ ] Are caches being used effectively?
- [ ] Are workflows skipping unnecessary runs?
- [ ] Are matrix builds optimized?
- [ ] Are dependencies installed efficiently?

Troubleshooting

Workflow Not Triggering

Check trigger configuration:

yaml

# Make sure triggers match your intent
on:
  issues:
    types: [opened, edited]  # Not just [opened]
  pull_request:
    types: [opened, synchronize]  # Include synchronize for new commits

Permission Denied Errors

Ensure proper permissions:

yaml

permissions:
  contents: write  # Required for file changes
  issues: write    # Required for issue operations
  pull-requests: write  # Required for PR operations

AI Model Timeouts

Use streaming and set appropriate timeouts:

markdown

## Configuration

- Model: claude-3-5-sonnet-20241022
- Max tokens: 4000
- Timeout: 300 seconds
- Stream: true

Rate Limiting

Implement backoff and respect rate limits:

markdown

## Rate Limiting

- Wait 1 second between API calls
- Use conditional requests (If-None-Match headers)
- Cache responses when possible
- Batch operations where supported

Debugging Workflows

Enable debug logging:

yaml

jobs:
  debug:
    runs-on: ubuntu-latest
    steps:
      - uses: github/gh-aw@v1
        with:
          workflow: .github/workflows/my-workflow.md
          debug: true
        env:
          ACTIONS_STEP_DEBUG: true

Cost Management

Track and limit costs:

markdown

imports: [shared/reporting.md]

## Cost Controls

- Maximum tokens per run: 100,000
- Alert threshold: $10/day
- Enable cost tracking in reports
- Use cheaper models for simple tasks (gpt-4o-mini)

Best Practices

Start Simple: Begin with basic workflows (issue triage) before complex ones (code generation)
Test Locally: Use
```
gh-aw run
```
to test workflows before deploying
Monitor Costs: Enable cost tracking and set budgets
Iterate: Refine agent instructions based on actual behavior
Use Shared Fragments: Reuse common patterns from the shared library
Clear Instructions: Write explicit, step-by-step instructions for agents
Error Handling: Include fallback behavior for common failure cases
Human Review: For destructive operations, create PRs instead of direct commits

github-agentic-workflows

NPX Install

Tags

SKILL.md Content

GitHub Agentic Workflows

What It Does

Installation

Prerequisites

Basic Setup

Workflow Structure

Example: Issue Triage Workflow

Key Workflow Types

Maintainer Workflows

Code Review Workflows

Documentation Workflows

Custom Workflow Creation

Basic Template

Using Shared Fragments

Advanced: MCP Server Integration

Configuration

Environment Variables

Workflow Permissions

Common Patterns

Command-Triggered Workflows

Scheduled Maintenance

Multi-Stage Workflows

Conditional Execution

Real-World Examples

Example 1: Bug Fix Automation

Example 2: Documentation Sync

Example 3: CI Cost Optimizer

Troubleshooting

Workflow Not Triggering

Permission Denied Errors

AI Model Timeouts

Rate Limiting

Debugging Workflows

Cost Management

Best Practices

Resources