github-agentic-workflows

# GitHub Agentic Workflows > Skill by [ara.so](https://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 1. GitHub repository with Actions enabled 2. GitHub App or Personal Access Token with appropriate permissions 3. Access to an AI model provider (OpenAI, Anthropic, etc.) ### Basic Setup 1. 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 ``` 2. Create `.github/workflows` directory in your repository: ```bash mkdir -p .github/workflows ``` 3. 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 ``` 4. 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: 1. **YAML file** (`.github/workflows/*.yml`) - GitHub Actions configuration 2. **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