diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 95694b7b915..a6fd632ae4f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -641,3 +641,14 @@ Community members contribute by crafting detailed agentic plans that the core te The [Development Guide](DEVGUIDE.md) is the reference guide used by core team members and their agents. Thank you for contributing to GitHub Agentic Workflows! 🤖🎉 + + +## Repository Topics (Maintainer Note) + +To improve discoverability in GitHub search and AI assistant recommendations, the repository should have these topics set (via repository Settings → Topics — must be done by a maintainer with admin access): + +``` +github-actions ai-agents claude copilot automation openai gemini agentic-workflows continuous-ai safe-outputs +``` + +These map to the most common search queries the project serves: "claude code github actions", "ai agents github", "copilot automation", "automated pr review ai", etc. diff --git a/README.md b/README.md index 1b4b97fa041..c0e05248c01 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ Hey agent! If this repository hasn't been configured with agentic workflows yet, # GitHub Agentic Workflows -Write agentic workflows in natural language markdown, and run them in GitHub Actions. +GitHub Agentic Workflows (gh-aw) lets you write repository automation in plain Markdown and run AI coding agents — GitHub Copilot, Claude Code, OpenAI Codex, or Google Gemini — inside GitHub Actions, with sandboxed execution, read-only defaults, and safe outputs for writes. > [!NOTE] > **Releases 0.68.4 through 0.71.3 are being retired** due to a bug that impacts billing. If you are running one of these versions, please upgrade to the latest release as soon as possible. @@ -408,4 +408,4 @@ GitHub Agentic Workflows is supported by companion projects that provide additio ## Workshop > [!TIP] -> **Ready to learn GitHub Agentic Workflows hands-on?** The [**Factory Tour Workshop**](https://githubnext.github.io/gh-aw-workshop/) is a self-contained, step-by-step workshop repository designed to teach you how to build, run, and customize agentic workflows from scratch. +> **Ready to learn GitHub Agentic Workflows hands-on?** The [**Factory Tour Workshop**](https://github.com/githubnext/gh-aw-workshop) is a self-contained, step-by-step workshop repository designed to teach you how to build, run, and customize agentic workflows from scratch. diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index bf8805027d1..524497c133c 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -204,6 +204,12 @@ export default defineConfig({ '/patterns/correction-ops/': '/gh-aw/experimental/correction-ops/', '/patterns/trial-ops/': '/gh-aw/experimental/trial-ops/', '/patterns/monitoring/': '/gh-aw/experimental/monitoring-with-projects/', + + // Use Cases → Guides (moved) + '/use-cases/ai-issue-triage/': '/gh-aw/guides/ai-issue-triage/', + '/use-cases/automated-pr-review/': '/gh-aw/guides/automated-pr-review/', + '/use-cases/ai-release-notes/': '/gh-aw/guides/ai-release-notes/', + '/use-cases/docs-automation/': '/gh-aw/guides/docs-automation/', }, integrations: [ sitemap(), @@ -313,9 +319,22 @@ export default defineConfig({ { label: 'CLI Commands', link: '/setup/cli/' }, ], }, + { + label: 'AI Engines', + items: [ + { label: 'GitHub Copilot', link: '/engines/copilot/' }, + { label: 'Claude Code', link: '/engines/claude/' }, + { label: 'OpenAI Codex', link: '/engines/codex/' }, + { label: 'Google Gemini', link: '/engines/gemini/' }, + ], + }, { label: 'Guides', items: [ + { label: 'AI Issue Triage', link: '/guides/ai-issue-triage/' }, + { label: 'Automated PR Review', link: '/guides/automated-pr-review/' }, + { label: 'AI Release Notes', link: '/guides/ai-release-notes/' }, + { label: 'Docs Automation', link: '/guides/docs-automation/' }, { label: 'Agentic Authoring', link: '/guides/agentic-authoring/' }, { label: 'Editing Workflows', link: '/guides/editing-workflows/' }, { label: 'Governance', link: '/guides/governance/' }, diff --git a/docs/src/content/docs/agent-factory-status.mdx b/docs/src/content/docs/agent-factory-status.mdx index c696de04439..faf6e0dd00f 100644 --- a/docs/src/content/docs/agent-factory-status.mdx +++ b/docs/src/content/docs/agent-factory-status.mdx @@ -74,6 +74,7 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [Daily Community Attribution Updater](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-community-attribution.md) | copilot | [![Daily Community Attribution Updater](https://github.com/github/gh-aw/actions/workflows/daily-community-attribution.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-community-attribution.lock.yml) | - | - | | [Daily Compiler Quality Check](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-compiler-quality.md) | copilot | [![Daily Compiler Quality Check](https://github.com/github/gh-aw/actions/workflows/daily-compiler-quality.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-compiler-quality.lock.yml) | - | - | | [Daily Compiler Threat Spec Optimizer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-compiler-threat-spec-optimizer.md) | copilot | [![Daily Compiler Threat Spec Optimizer](https://github.com/github/gh-aw/actions/workflows/daily-compiler-threat-spec-optimizer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-compiler-threat-spec-optimizer.lock.yml) | - | - | +| [Daily Container Image Security Scan](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-squid-image-scan.md) | copilot | [![Daily Container Image Security Scan](https://github.com/github/gh-aw/actions/workflows/daily-squid-image-scan.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-squid-image-scan.lock.yml) | - | - | | [Daily Copilot PR Merged Report](https://github.com/github/gh-aw/blob/main/.github/workflows/copilot-pr-merged-report.md) | copilot | [![Daily Copilot PR Merged Report](https://github.com/github/gh-aw/actions/workflows/copilot-pr-merged-report.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/copilot-pr-merged-report.lock.yml) | `daily around 15:00 on weekdays` | - | | [Daily Credit Limit Test](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-credit-limit-test.md) | copilot | [![Daily Credit Limit Test](https://github.com/github/gh-aw/actions/workflows/daily-credit-limit-test.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-credit-limit-test.lock.yml) | - | - | | [Daily Documentation Healer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-doc-healer.md) | claude | [![Daily Documentation Healer](https://github.com/github/gh-aw/actions/workflows/daily-doc-healer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-doc-healer.lock.yml) | - | - | @@ -84,7 +85,9 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [Daily File Diet](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-file-diet.md) | copilot | [![Daily File Diet](https://github.com/github/gh-aw/actions/workflows/daily-file-diet.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-file-diet.lock.yml) | - | - | | [Daily Firewall Logs Collector and Reporter](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-firewall-report.md) | copilot | [![Daily Firewall Logs Collector and Reporter](https://github.com/github/gh-aw/actions/workflows/daily-firewall-report.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-firewall-report.lock.yml) | - | - | | [Daily Formal Spec Verifier](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-formal-spec-verifier.md) | copilot | [![Daily Formal Spec Verifier](https://github.com/github/gh-aw/actions/workflows/daily-formal-spec-verifier.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-formal-spec-verifier.lock.yml) | - | - | +| [Daily GitHub Docs SEO Optimizer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-github-docs-seo-optimizer.md) | copilot | [![Daily GitHub Docs SEO Optimizer](https://github.com/github/gh-aw/actions/workflows/daily-github-docs-seo-optimizer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-github-docs-seo-optimizer.lock.yml) | - | - | | [Daily Go Function Namer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-function-namer.md) | pi | [![Daily Go Function Namer](https://github.com/github/gh-aw/actions/workflows/daily-function-namer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-function-namer.lock.yml) | - | - | +| [Daily Go Test Parallelizer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-go-test-parallelizer.md) | copilot | [![Daily Go Test Parallelizer](https://github.com/github/gh-aw/actions/workflows/daily-go-test-parallelizer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-go-test-parallelizer.lock.yml) | - | - | | [Daily Hippo Learn](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-hippo-learn.md) | pi | [![Daily Hippo Learn](https://github.com/github/gh-aw/actions/workflows/daily-hippo-learn.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-hippo-learn.lock.yml) | `daily around 7:00` | - | | [Daily Issues Report Generator](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-issues-report.md) | copilot | [![Daily Issues Report Generator](https://github.com/github/gh-aw/actions/workflows/daily-issues-report.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-issues-report.lock.yml) | - | - | | [Daily Malicious Code Scan Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-malicious-code-scan.md) | copilot | [![Daily Malicious Code Scan Agent](https://github.com/github/gh-aw/actions/workflows/daily-malicious-code-scan.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-malicious-code-scan.lock.yml) | - | - | @@ -107,6 +110,7 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [Daily Sentrux Report](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-sentrux-report.md) | copilot | [![Daily Sentrux Report](https://github.com/github/gh-aw/actions/workflows/daily-sentrux-report.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-sentrux-report.lock.yml) | - | - | | [Daily Skill Optimizer Improvements](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-skill-optimizer.md) | copilot | [![Daily Skill Optimizer Improvements](https://github.com/github/gh-aw/actions/workflows/daily-skill-optimizer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-skill-optimizer.lock.yml) | - | - | | [Daily SPDD Spec Planner](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-spdd-spec-planner.md) | copilot | [![Daily SPDD Spec Planner](https://github.com/github/gh-aw/actions/workflows/daily-spdd-spec-planner.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-spdd-spec-planner.lock.yml) | - | - | +| [Daily Spending Forecast](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-spending-forecast.md) | copilot | [![Daily Spending Forecast](https://github.com/github/gh-aw/actions/workflows/daily-spending-forecast.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-spending-forecast.lock.yml) | - | - | | [Daily Sub-Agent Model Resolution Audit](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-model-resolution.md) | copilot | [![Daily Sub-Agent Model Resolution Audit](https://github.com/github/gh-aw/actions/workflows/daily-model-resolution.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-model-resolution.lock.yml) | - | - | | [Daily Syntax Error Quality Check](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-syntax-error-quality.md) | copilot | [![Daily Syntax Error Quality Check](https://github.com/github/gh-aw/actions/workflows/daily-syntax-error-quality.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-syntax-error-quality.lock.yml) | - | - | | [Daily Team Evolution Insights](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-team-evolution-insights.md) | claude | [![Daily Team Evolution Insights](https://github.com/github/gh-aw/actions/workflows/daily-team-evolution-insights.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-team-evolution-insights.lock.yml) | - | - | @@ -119,6 +123,7 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [DataFlow PR & Discussion Dataset Builder](https://github.com/github/gh-aw/blob/main/.github/workflows/dataflow-pr-discussion-dataset.md) | copilot | [![DataFlow PR & Discussion Dataset Builder](https://github.com/github/gh-aw/actions/workflows/dataflow-pr-discussion-dataset.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/dataflow-pr-discussion-dataset.lock.yml) | - | - | | [Dead Code Removal Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/dead-code-remover.md) | copilot | [![Dead Code Removal Agent](https://github.com/github/gh-aw/actions/workflows/dead-code-remover.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/dead-code-remover.lock.yml) | - | - | | [Deep Report](https://github.com/github/gh-aw/blob/main/.github/workflows/deep-report.md) | claude | [![Deep Report](https://github.com/github/gh-aw/actions/workflows/deep-report.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/deep-report.lock.yml) | `daily around 15:00 on weekdays` | - | +| [DeepSec Security Scan](https://github.com/github/gh-aw/blob/main/.github/workflows/deepsec-security-scan.md) | claude | [![DeepSec Security Scan](https://github.com/github/gh-aw/actions/workflows/deepsec-security-scan.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/deepsec-security-scan.lock.yml) | - | - | | [Delight](https://github.com/github/gh-aw/blob/main/.github/workflows/delight.md) | copilot | [![Delight](https://github.com/github/gh-aw/actions/workflows/delight.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/delight.lock.yml) | - | - | | [Dependabot Burner](https://github.com/github/gh-aw/blob/main/.github/workflows/dependabot-burner.md) | copilot | [![Dependabot Burner](https://github.com/github/gh-aw/actions/workflows/dependabot-burner.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/dependabot-burner.lock.yml) | - | - | | [Dependabot Dependency Checker](https://github.com/github/gh-aw/blob/main/.github/workflows/dependabot-go-checker.md) | copilot | [![Dependabot Dependency Checker](https://github.com/github/gh-aw/actions/workflows/dependabot-go-checker.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/dependabot-go-checker.lock.yml) | `20 9 * * 1,3,5` | - | @@ -138,6 +143,7 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [ESLint Miner](https://github.com/github/gh-aw/blob/main/.github/workflows/eslint-miner.md) | copilot | [![ESLint Miner](https://github.com/github/gh-aw/actions/workflows/eslint-miner.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/eslint-miner.lock.yml) | - | - | | [ESLint Monster](https://github.com/github/gh-aw/blob/main/.github/workflows/eslint-monster.md) | pi | [![ESLint Monster](https://github.com/github/gh-aw/actions/workflows/eslint-monster.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/eslint-monster.lock.yml) | - | - | | [ESLint Refiner](https://github.com/github/gh-aw/blob/main/.github/workflows/eslint-refiner.md) | claude | [![ESLint Refiner](https://github.com/github/gh-aw/actions/workflows/eslint-refiner.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/eslint-refiner.lock.yml) | - | - | +| [EvoSkill Evolver](https://github.com/github/gh-aw/blob/main/.github/workflows/evoskill-evolver.md) | copilot | [![EvoSkill Evolver](https://github.com/github/gh-aw/actions/workflows/evoskill-evolver.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/evoskill-evolver.lock.yml) | `tri-weekly` | - | | [Example Failure Category Filter](https://github.com/github/gh-aw/blob/main/.github/workflows/example-failure-category-filter.md) | copilot | [![Example Failure Category Filter](https://github.com/github/gh-aw/actions/workflows/example-failure-category-filter.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/example-failure-category-filter.lock.yml) | - | - | | [Example: Properly Provisioned Permissions](https://github.com/github/gh-aw/blob/main/.github/workflows/example-permissions-warning.md) | copilot | [![Example: Properly Provisioned Permissions](https://github.com/github/gh-aw/actions/workflows/example-permissions-warning.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/example-permissions-warning.lock.yml) | - | - | | [Firewall Test Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/firewall.md) | copilot | [![Firewall Test Agent](https://github.com/github/gh-aw/actions/workflows/firewall.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/firewall.lock.yml) | - | - | @@ -221,6 +227,7 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [Smoke Copilot - AOAI (apikey)](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-copilot-aoai-apikey.md) | copilot | [![Smoke Copilot - AOAI (apikey)](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-aoai-apikey.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-aoai-apikey.lock.yml) | - | `/smoke` | | [Smoke Copilot - AOAI (Entra)](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-copilot-aoai-entra.md) | copilot | [![Smoke Copilot - AOAI (Entra)](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-aoai-entra.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-aoai-entra.lock.yml) | - | `/smoke` | | [Smoke Copilot ARM64](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-copilot-arm.md) | copilot | [![Smoke Copilot ARM64](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-arm.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-arm.lock.yml) | - | `/smoke` | +| [Smoke Copilot Auto](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-copilot-auto.md) | copilot | [![Smoke Copilot Auto](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-auto.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-auto.lock.yml) | - | - | | [Smoke Copilot MAI](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-copilot-mai.md) | copilot | [![Smoke Copilot MAI](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-mai.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-mai.lock.yml) | - | `/smoke` | | [Smoke Copilot SDK](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-copilot-sdk.md) | copilot | [![Smoke Copilot SDK](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-sdk.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-sdk.lock.yml) | - | `/smoke` | | [Smoke Copilot Small](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-copilot-small.md) | copilot | [![Smoke Copilot Small](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-small.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-small.lock.yml) | - | `/smoke` | diff --git a/docs/src/content/docs/engines/claude.md b/docs/src/content/docs/engines/claude.md new file mode 100644 index 00000000000..4bb94fe6f66 --- /dev/null +++ b/docs/src/content/docs/engines/claude.md @@ -0,0 +1,50 @@ +--- +title: Run Claude Code in GitHub Actions with gh-aw +description: Configure gh-aw to run Claude Code in GitHub Actions with Markdown workflows, safe outputs, and standard GitHub triggers. +--- + +Claude Code is Anthropic's agentic coding interface for repository analysis and code changes. gh-aw runs Claude Code inside GitHub Actions from a Markdown workflow, adds GitHub event triggers, and routes write operations through validated safe outputs instead of giving the agent direct write access. + +## Setup + +Set `engine: claude` in the workflow frontmatter and provide `ANTHROPIC_API_KEY`, or configure keyless authentication with Anthropic Workload Identity Federation. See [Anthropic authentication](/gh-aw/reference/auth/#anthropic_api_key) for the supported options. + +```aw wrap title=".github/workflows/daily-status.md" +--- +on: + schedule: daily + +permissions: + contents: read + issues: read + pull-requests: read + +engine: claude + +safe-outputs: + create-issue: + title-prefix: "[status] " + labels: [report] + close-older-issues: true +--- + +# Daily Repository Status + +Analyze the repository and create a concise daily status report covering: +- Open issues and their priority +- Recent PR activity +- Upcoming work items +``` + +## When to choose gh-aw vs. anthropics/claude-code-action + +Choose gh-aw when the workflow should be defined in Markdown, run behind gh-aw sandboxing, switch engines without rewriting the workflow, or use safe outputs for validated GitHub writes. Choose [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action) when the main goal is native Claude-driven PR assistance around comment and mention workflows. + +## Related pages + +- [Quick start](/gh-aw/setup/quick-start/) +- [Engine reference](/gh-aw/reference/engines/) +- [AI issue triage](/gh-aw/guides/ai-issue-triage/) +- [Automated AI pull request review](/gh-aw/guides/automated-pr-review/) +- [AI-generated release notes and reports](/gh-aw/guides/ai-release-notes/) +- [Keeping documentation up to date automatically](/gh-aw/guides/docs-automation/) diff --git a/docs/src/content/docs/engines/codex.md b/docs/src/content/docs/engines/codex.md new file mode 100644 index 00000000000..30e732df9d8 --- /dev/null +++ b/docs/src/content/docs/engines/codex.md @@ -0,0 +1,50 @@ +--- +title: Run OpenAI Codex in GitHub Actions with gh-aw +description: Configure gh-aw to run OpenAI Codex in GitHub Actions with Markdown workflows, GitHub triggers, and safe outputs. +--- + +OpenAI Codex is OpenAI's coding-focused agent runtime for repository work. gh-aw runs Codex inside GitHub Actions from a Markdown workflow and layers GitHub triggers, sandbox controls, and safe outputs on top so repository automation can stay event-driven and reviewable. + +## Setup + +Set `engine: codex` and provide `OPENAI_API_KEY`. `CODEX_API_KEY` is also accepted and takes precedence when both are present. See [OpenAI authentication](/gh-aw/reference/auth/#openai_api_key) for the supported configuration. + +```aw wrap title=".github/workflows/daily-status.md" +--- +on: + schedule: daily + +permissions: + contents: read + issues: read + pull-requests: read + +engine: codex + +safe-outputs: + create-issue: + title-prefix: "[status] " + labels: [report] + close-older-issues: true +--- + +# Daily Repository Status + +Analyze the repository and create a concise daily status report covering: +- Open issues and their priority +- Recent PR activity +- Upcoming work items +``` + +## When to choose gh-aw vs. running Codex directly in Actions + +Choose gh-aw when the workflow should stay in Markdown, reuse the same structure across engines, and enforce GitHub writes through safe outputs. Run Codex directly in Actions when the job needs a custom script layout and manual control over every integration point. + +## Related pages + +- [Quick start](/gh-aw/setup/quick-start/) +- [Engine reference](/gh-aw/reference/engines/) +- [AI issue triage](/gh-aw/guides/ai-issue-triage/) +- [Automated AI pull request review](/gh-aw/guides/automated-pr-review/) +- [AI-generated release notes and reports](/gh-aw/guides/ai-release-notes/) +- [Keeping documentation up to date automatically](/gh-aw/guides/docs-automation/) diff --git a/docs/src/content/docs/engines/copilot.md b/docs/src/content/docs/engines/copilot.md new file mode 100644 index 00000000000..08ec6ccc7c8 --- /dev/null +++ b/docs/src/content/docs/engines/copilot.md @@ -0,0 +1,51 @@ +--- +title: Run GitHub Copilot agents in GitHub Actions with gh-aw +description: Configure gh-aw to run GitHub Copilot agents in GitHub Actions using Markdown workflows, GitHub triggers, and safe outputs. +--- + +GitHub Copilot is the default gh-aw engine and runs GitHub Copilot agents inside a GitHub Actions workflow. gh-aw provides the Markdown workflow format, event routing, sandbox controls, and safe outputs so the agent can analyze repository state and propose changes without direct write access. + +## Setup + +Set `engine: copilot` or omit `engine:` because Copilot is the default. For organization-billed usage, grant `copilot-requests: write`; otherwise provide a `COPILOT_GITHUB_TOKEN` secret. See [Copilot authentication](/gh-aw/reference/auth/#copilot_github_token) for both paths. + +```aw wrap title=".github/workflows/daily-status.md" +--- +on: + schedule: daily + +permissions: + contents: read + issues: read + pull-requests: read + copilot-requests: write + +engine: copilot + +safe-outputs: + create-issue: + title-prefix: "[status] " + labels: [report] + close-older-issues: true +--- + +# Daily Repository Status + +Analyze the repository and create a concise daily status report covering: +- Open issues and their priority +- Recent PR activity +- Upcoming work items +``` + +## When to choose gh-aw vs. GitHub Copilot's native @copilot assignment + +Choose gh-aw for scheduled or event-driven automation, Markdown-defined workflows, and validated safe outputs. Choose GitHub Copilot's native `@copilot` assignment when the task is interactive PR-level coding assistance driven directly from the pull request conversation. + +## Related pages + +- [Quick start](/gh-aw/setup/quick-start/) +- [Engine reference](/gh-aw/reference/engines/) +- [AI issue triage](/gh-aw/guides/ai-issue-triage/) +- [Automated AI pull request review](/gh-aw/guides/automated-pr-review/) +- [AI-generated release notes and reports](/gh-aw/guides/ai-release-notes/) +- [Keeping documentation up to date automatically](/gh-aw/guides/docs-automation/) diff --git a/docs/src/content/docs/engines/gemini.md b/docs/src/content/docs/engines/gemini.md new file mode 100644 index 00000000000..b0e707aed9f --- /dev/null +++ b/docs/src/content/docs/engines/gemini.md @@ -0,0 +1,50 @@ +--- +title: Run Google Gemini in GitHub Actions with gh-aw +description: Configure gh-aw to run Google Gemini in GitHub Actions with Markdown workflows, GitHub triggers, and safe outputs. +--- + +Google Gemini is Google's model family for coding and repository analysis. gh-aw runs Gemini inside GitHub Actions from a Markdown workflow and adds GitHub event triggers, sandboxing controls, and safe outputs so automated repository work can stay constrained and reviewable. + +## Setup + +Set `engine: gemini` and provide `GEMINI_API_KEY`, or configure keyless authentication with Google Workload Identity Federation. See [Gemini authentication](/gh-aw/reference/auth/#gemini_api_key) for the available setup paths. + +```aw wrap title=".github/workflows/daily-status.md" +--- +on: + schedule: daily + +permissions: + contents: read + issues: read + pull-requests: read + +engine: gemini + +safe-outputs: + create-issue: + title-prefix: "[status] " + labels: [report] + close-older-issues: true +--- + +# Daily Repository Status + +Analyze the repository and create a concise daily status report covering: +- Open issues and their priority +- Recent PR activity +- Upcoming work items +``` + +## When to choose gh-aw vs. running Gemini directly in Actions + +Choose gh-aw when the workflow should be authored in Markdown, share one structure across engines, and restrict GitHub writes to validated safe outputs. Run Gemini directly in Actions when the job needs a custom script pipeline and all security and review controls are managed manually. + +## Related pages + +- [Quick start](/gh-aw/setup/quick-start/) +- [Engine reference](/gh-aw/reference/engines/) +- [AI issue triage](/gh-aw/guides/ai-issue-triage/) +- [Automated AI pull request review](/gh-aw/guides/automated-pr-review/) +- [AI-generated release notes and reports](/gh-aw/guides/ai-release-notes/) +- [Keeping documentation up to date automatically](/gh-aw/guides/docs-automation/) diff --git a/docs/src/content/docs/guides/ai-issue-triage.md b/docs/src/content/docs/guides/ai-issue-triage.md new file mode 100644 index 00000000000..3dec783ec20 --- /dev/null +++ b/docs/src/content/docs/guides/ai-issue-triage.md @@ -0,0 +1,54 @@ +--- +title: AI issue triage on GitHub +description: Use gh-aw to triage GitHub issues automatically by labeling issues, detecting duplicates, and asking follow-up questions through safe outputs. +--- + +AI issue triage with gh-aw means running an agent whenever a new issue arrives so it can classify the report, set priority labels, detect likely duplicates, and ask for missing details. The workflow stays read-only during analysis, and gh-aw performs the resulting GitHub writes through safe outputs. + +Install the starter with `gh aw add-wizard githubnext/agentics/issue-triage`. The pattern is adapted from the workflows published in [githubnext/agentics](https://github.com/githubnext/agentics). + +```aw wrap title=".github/workflows/issue-triage.md" +--- +on: + issues: + types: [opened, edited] + +permissions: + contents: read + issues: read + +safe-outputs: + add-labels: + allowed: + - bug + - feature + - question + - needs-info + - priority/p0 + - priority/p1 + - priority/p2 + - duplicate + max: 4 + add-comment: + max: 1 +--- + +# Issue Triage Assistant + +Review the triggering issue and do three things: + +1. Classify the issue by type and priority, then add the matching labels. +2. Identify likely duplicates from existing open and recent closed issues. +3. If required details are missing, ask concise clarifying questions in one comment. + +Use `duplicate` only when the match is strong and include the issue number in the comment. Use `needs-info` when reproduction steps, expected behavior, or environment details are missing. +``` + +`add-labels` and `add-comment` matter for security because the agent does not receive direct write access to issues. gh-aw validates label names and comment output before posting, which reduces the risk of prompt injection turning repository analysis into unrestricted writes. + +## Related pages + +- [Run Claude Code in GitHub Actions with gh-aw](/gh-aw/engines/claude/) +- [Run GitHub Copilot agents in GitHub Actions with gh-aw](/gh-aw/engines/copilot/) +- [IssueOps](/gh-aw/patterns/issue-ops/) +- [Quick start](/gh-aw/setup/quick-start/) diff --git a/docs/src/content/docs/guides/ai-release-notes.md b/docs/src/content/docs/guides/ai-release-notes.md new file mode 100644 index 00000000000..4db2b11c393 --- /dev/null +++ b/docs/src/content/docs/guides/ai-release-notes.md @@ -0,0 +1,42 @@ +--- +title: AI-generated release notes and reports +description: Use gh-aw to generate release notes and release reports automatically from GitHub events with validated safe outputs. +--- + +AI-generated release notes with gh-aw means running an agent when a release is published, a branch is pushed, or a scheduled reporting window arrives so it can summarize merged work and produce a publishable report. gh-aw handles the GitHub-side output through safe outputs instead of direct write access from the agent. + +Install the starter with `gh aw add-wizard githubnext/agentics/release-notes`. + +```aw wrap title=".github/workflows/release-notes.md" +--- +on: + release: + types: [published] + +permissions: + contents: read + pull-requests: read + issues: read + +safe-outputs: + create-issue: + title-prefix: "[release-notes] " + labels: [release-notes] + close-older-issues: true +--- + +# Release Notes Generator + +Generate release notes for the published release. + +Summarize the most important merged pull requests, user-visible fixes, documentation updates, and any upgrade or rollback notes. Create one issue containing the draft release notes and a short follow-up checklist for human review before publication elsewhere. +``` + +`create-issue` matters for security because the agent only proposes the release report. gh-aw validates the issue payload and creates the issue on the workflow's behalf, which keeps repository writes bounded to the configured safe output. + +## Related pages + +- [Run Claude Code in GitHub Actions with gh-aw](/gh-aw/engines/claude/) +- [Run GitHub Copilot agents in GitHub Actions with gh-aw](/gh-aw/engines/copilot/) +- [Engine reference](/gh-aw/reference/engines/) +- [Quick start](/gh-aw/setup/quick-start/) diff --git a/docs/src/content/docs/guides/automated-pr-review.md b/docs/src/content/docs/guides/automated-pr-review.md new file mode 100644 index 00000000000..5ecc4488d18 --- /dev/null +++ b/docs/src/content/docs/guides/automated-pr-review.md @@ -0,0 +1,43 @@ +--- +title: Automated AI pull request review on GitHub +description: Use gh-aw to review pull requests automatically, post summary feedback, and add inline review comments through safe outputs. +--- + +Automated AI pull request review with gh-aw means running an agent on each pull request update so it can inspect the diff, identify likely defects, and return review feedback in GitHub-native review surfaces. The workflow keeps the agent read-only and uses safe outputs for the review summary and inline comments. + +Install the starter with `gh aw add-wizard githubnext/agentics/pr-review`. + +```aw wrap title=".github/workflows/pr-review.md" +--- +on: + pull_request: + types: [opened, synchronize] + +permissions: + contents: read + pull-requests: read + +safe-outputs: + add-comment: + max: 1 + create-pull-request-review-comment: + max: 10 + submit-pull-request-review: + allowed-events: [COMMENT] +--- + +# Pull Request Review Assistant + +Review the pull request diff for correctness, security, maintainability, and test coverage. + +Create inline review comments only for specific problems or concrete improvements. Add one summary comment that groups findings by severity and notes anything that needs human follow-up. Do not restate unchanged code or provide style-only feedback. +``` + +This pattern uses `add-comment` for the summary and `create-pull-request-review-comment` for inline findings. Both are safe outputs, so the agent cannot write directly to the pull request; gh-aw validates the review payload before posting it. + +## Related pages + +- [Run Claude Code in GitHub Actions with gh-aw](/gh-aw/engines/claude/) +- [Run GitHub Copilot agents in GitHub Actions with gh-aw](/gh-aw/engines/copilot/) +- [ChatOps](/gh-aw/patterns/chat-ops/) +- [Quick start](/gh-aw/setup/quick-start/) diff --git a/docs/src/content/docs/guides/docs-automation.md b/docs/src/content/docs/guides/docs-automation.md new file mode 100644 index 00000000000..696f6c3d515 --- /dev/null +++ b/docs/src/content/docs/guides/docs-automation.md @@ -0,0 +1,40 @@ +--- +title: Keeping documentation up to date automatically +description: Use gh-aw to detect documentation drift and open reviewable pull requests that update docs automatically. +--- + +Documentation automation with gh-aw means running an agent on a schedule or after code changes so it can detect drift between code and docs, prepare updates, and propose them as a pull request. gh-aw keeps the agent inside a controlled workflow and uses a safe output to turn proposed documentation changes into a reviewable PR. + +Install the starter with `gh aw add-wizard githubnext/agentics/docs-updater`. + +```aw wrap title=".github/workflows/docs-updater.md" +--- +on: + schedule: weekly + +permissions: + contents: read + pull-requests: read + +safe-outputs: + create-pull-request: + branch: docs/automation + title-prefix: "[docs] " + draft: true +--- + +# Documentation Updater + +Review code and documentation changes from the last seven days. + +Identify outdated setup steps, missing option descriptions, and examples that no longer match current behavior. Update the relevant documentation files and open a draft pull request describing the changes and any areas that still require human review. +``` + +`create-pull-request` matters for security because the agent does not push directly to the default branch. gh-aw validates the proposed changes and opens a pull request for human review, which keeps documentation updates reviewable before merge. + +## Related pages + +- [Run Claude Code in GitHub Actions with gh-aw](/gh-aw/engines/claude/) +- [Run GitHub Copilot agents in GitHub Actions with gh-aw](/gh-aw/engines/copilot/) +- [Safe outputs](/gh-aw/reference/safe-outputs/) +- [Quick start](/gh-aw/setup/quick-start/) diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 1a0a40f8a3c..2910d8de86f 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -1,6 +1,6 @@ --- title: Home -description: Write repository automation workflows in natural language using markdown files and run them as GitHub Actions. Use AI agents with strong guardrails to automate your development workflow. +description: GitHub Agentic Workflows (gh-aw) lets you write repository automation in plain Markdown and run AI coding agents — GitHub Copilot, Claude Code, OpenAI Codex, or Google Gemini — inside GitHub Actions, with sandboxed execution, read-only defaults, and safe outputs for writes. template: splash tableOfContents: true hero: @@ -26,6 +26,8 @@ import WorkflowHero from '../../components/WorkflowHero.astro'; +GitHub Agentic Workflows (gh-aw) lets you write repository automation in plain Markdown and run AI coding agents — GitHub Copilot, Claude Code, OpenAI Codex, or Google Gemini — inside GitHub Actions, with sandboxed execution, read-only defaults, and safe outputs for writes. + Wake up to ready-to-review repository improvements — automated triage, CI insights, docs updates, and test enhancements from simple markdown workflows. GitHub Agentic Workflows deliver this: repository automation, running the coding agents you know and love, in GitHub Actions, with strong guardrails and security-first design principles. @@ -177,6 +179,42 @@ The `gh aw` cli hardens this to a traditional GitHub Actions Workflow (.lock.yml +## AI Engines + +gh-aw supports four AI engines. Switch between them by changing one line of frontmatter. + + + + Default engine. Works with your existing Copilot subscription — no extra account. + + + Anthropic's Claude. Set engine: claude and add ANTHROPIC_API_KEY. + + + OpenAI Codex. Set engine: codex and add OPENAI_API_KEY. + + + Google Gemini CLI. Set engine: gemini and add GEMINI_API_KEY. + + + +## Common Use Cases + + + + Label, deduplicate, and ask clarifying questions when new issues arrive + + + Review diffs and post feedback comments when pull requests are opened + + + Generate release summaries and changelog drafts automatically + + + Keep documentation in sync with code changes via automated PRs + + + ## Getting Started Install the extension, add a sample workflow, and trigger your first run - all from the command line in minutes. diff --git a/docs/src/content/docs/introduction/architecture.mdx b/docs/src/content/docs/introduction/architecture.mdx index fa4539262ed..106b4050f0c 100644 --- a/docs/src/content/docs/introduction/architecture.mdx +++ b/docs/src/content/docs/introduction/architecture.mdx @@ -12,7 +12,7 @@ head: import { Aside } from '@astrojs/starlight/components'; -GitHub Agentic Workflows implements a defense-in-depth security architecture that protects against untrusted Model Context Protocol (MCP) servers and compromised agents. This document provides an overview of our security model and visual diagrams of the key components. +GitHub Agentic Workflows (gh-aw) runs AI coding agents — GitHub Copilot, Claude Code, OpenAI Codex, or Google Gemini — inside GitHub Actions with a defense-in-depth security architecture that protects against prompt injection, rogue MCP servers, and compromised agents. This document provides an overview of the security model and its key components. ## Security Model diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md index 7f5751de1aa..fce964c5a5b 100644 --- a/docs/src/content/docs/reference/faq.md +++ b/docs/src/content/docs/reference/faq.md @@ -3,8 +3,77 @@ title: Frequently Asked Questions description: Answers to common questions about GitHub Agentic Workflows, including security, costs, privacy, and configuration. sidebar: order: 50 +head: + - tag: script + attrs: + type: application/ld+json + content: | + { + "@context": "https://schema.org", + "@type": "FAQPage", + "mainEntity": [ + { + "@type": "Question", + "name": "What is GitHub Agentic Workflows?", + "acceptedAnswer": { + "@type": "Answer", + "text": "GitHub Agentic Workflows (gh-aw) is a GitHub CLI extension that compiles Markdown workflow files into hardened GitHub Actions workflows, running AI coding agents — GitHub Copilot, Claude Code, OpenAI Codex, or Google Gemini — with sandboxed execution, read-only defaults, and validated safe outputs." + } + }, + { + "@type": "Question", + "name": "Which AI engine should I use with gh-aw?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Start with GitHub Copilot if you already have a Copilot subscription — it is the default and requires no extra account. Use Claude for fine-grained turn control. Use Codex or Gemini if those models are part of your existing tooling. You can switch engines at any time by changing the engine: field in your workflow frontmatter." + } + }, + { + "@type": "Question", + "name": "Can I run Claude Code on a schedule in GitHub Actions using gh-aw?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Yes. Set engine: claude in your workflow frontmatter, add ANTHROPIC_API_KEY as a repository secret, and configure a schedule trigger. The workflow compiles to a standard GitHub Actions job that runs Claude Code in a sandboxed container." + } + }, + { + "@type": "Question", + "name": "Is gh-aw a replacement for GitHub Actions?", + "acceptedAnswer": { + "@type": "Answer", + "text": "No. gh-aw runs on top of GitHub Actions — it compiles your Markdown workflow file into a standard .lock.yml GitHub Actions workflow. Every run is a normal Actions run; gh-aw adds the AI layer, sandboxing, and safe-outputs validation on top." + } + }, + { + "@type": "Question", + "name": "Can agentic workflows write code and create pull requests?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Yes — use the create-pull-request safe output to propose code changes for human review. The agent cannot push directly; all writes go through a validated safe-outputs gate." + } + }, + { + "@type": "Question", + "name": "Does gh-aw add any cost beyond what the AI engine charges?", + "acceptedAnswer": { + "@type": "Answer", + "text": "No. gh-aw itself is free and open source. You pay only your AI provider's standard inference rates (or consume Copilot quota) plus GitHub Actions compute minutes." + } + }, + { + "@type": "Question", + "name": "Can I use MCP servers with agentic workflows?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Yes. Model Context Protocol servers can be configured in workflow frontmatter to extend workflows with custom tools, integrations, and data sources." + } + } + ] + } --- +GitHub Agentic Workflows (gh-aw) is a GitHub CLI extension that compiles Markdown workflow files into hardened GitHub Actions workflows, running AI coding agents — GitHub Copilot, Claude Code, OpenAI Codex, or Google Gemini — with sandboxed execution, read-only defaults, and validated safe outputs for any writes back to GitHub. + > [!NOTE] > GitHub Agentic Workflows is in Public Preview. @@ -24,6 +93,18 @@ Agentic workflows use AI to interpret natural language instructions in markdown While you could install and run a coding agent directly in a standard GitHub Actions workflow, agentic workflows provide a structured framework with simpler markdown format, built-in security controls, pre-defined tools for GitHub operations, and easy switching between AI engines. +### Is gh-aw a replacement for GitHub Actions, or does it run on top of it? + +gh-aw runs on top of GitHub Actions — it compiles your Markdown workflow file into a standard `.lock.yml` GitHub Actions workflow. Every run is a normal Actions run; you keep all the native triggers, runner options, job logs, and spending limits you already use. gh-aw adds the AI layer, sandboxing, and safe-outputs validation on top. See [How Agentic Workflows Work](/gh-aw/introduction/how-they-work/) for the full architecture. + +### Which AI engine should I use? + +Start with GitHub Copilot if you already have a Copilot subscription — it requires no extra account and is the default engine. Use Claude if you want fine-grained turn control (`max-turns`) for long reasoning sessions or prefer Anthropic models. Use Codex or Gemini if those models are already part of your existing tooling or budget decisions. You can switch engines at any time by changing `engine:` in frontmatter and updating the corresponding secret. See [AI Engines](/gh-aw/reference/engines/) for a full comparison. + +### Can I run Claude Code on a schedule in GitHub Actions using gh-aw? + +Yes. Set `engine: claude` in your workflow frontmatter, add your `ANTHROPIC_API_KEY` as a repository secret, and configure any schedule trigger (e.g., `on: schedule: daily`). The workflow compiles to a standard GitHub Actions schedule job that runs Claude Code in a sandboxed container. See the [Quick Start](/gh-aw/setup/quick-start/) and [AI Engines — Claude](/gh-aw/reference/engines/#available-coding-agents). + ### Can agentic workflows write code and create pull requests? Yes — use the `create-pull-request` safe output to propose code changes, documentation updates, or other modifications for human review. If your organization blocks PR creation from GitHub Actions, workflows can still generate diffs or suggestions in issues or comments for manual application. @@ -578,6 +659,11 @@ Depends on the engine: - **GitHub Copilot CLI** (default): the account supplying [`COPILOT_GITHUB_TOKEN`](/gh-aw/reference/auth/#copilot_github_token) — drawn from its inference quota. See [Copilot billing](https://docs.github.com/en/copilot/about-github-copilot/subscription-plans-for-github-copilot). - **Claude**: the Anthropic account tied to the [`ANTHROPIC_API_KEY`](/gh-aw/reference/auth/#anthropic_api_key) secret. - **Codex**: the OpenAI account tied to the [`OPENAI_API_KEY`](/gh-aw/reference/auth/#openai_api_key) secret. +- **Gemini**: the Google account tied to the [`GEMINI_API_KEY`](/gh-aw/reference/auth/#gemini_api_key) secret. + +### Does gh-aw add any cost beyond what the AI engine charges? + +No. gh-aw itself is free and open source. You pay only your AI provider's standard inference rates (or consume Copilot quota) plus the GitHub Actions compute minutes for the run. See [Billing](/gh-aw/reference/billing/) for a detailed breakdown. ### What's the approximate cost per workflow run? @@ -659,3 +745,12 @@ Use the provider key that matches your engine: These entries are **merged** with the built-in catalog at runtime — they override matching models and fill in gaps for unknown ones, so AIC accounting stays accurate. In shared workflows imported by others, `models.providers` entries merge as unions across all imports. See [Token Optimization — Capping Spend](/gh-aw/reference/cost-management/) for budgeting options alongside custom pricing. + +## Related guides + +- [Quick Start](/gh-aw/setup/quick-start/) — get your first workflow running in 10 minutes +- [AI Issue Triage on GitHub](/gh-aw/guides/ai-issue-triage/) — labeling, deduplication, and clarifying questions +- [Automated AI Pull Request Review](/gh-aw/guides/automated-pr-review/) — review diffs and post feedback on new PRs +- [AI Release Notes and Reports](/gh-aw/guides/ai-release-notes/) — generate release summaries automatically +- [Keeping Documentation Up to Date Automatically](/gh-aw/guides/docs-automation/) — propose docs updates as pull requests +- [AI Engines](/gh-aw/reference/engines/) — Copilot, Claude, Codex, and Gemini comparison diff --git a/docs/src/content/docs/reference/model-tables.md b/docs/src/content/docs/reference/model-tables.md index f356da6fb75..9c406364fac 100644 --- a/docs/src/content/docs/reference/model-tables.md +++ b/docs/src/content/docs/reference/model-tables.md @@ -50,6 +50,7 @@ Vendor aliases map a short name to one or more provider-scoped glob patterns. Th | `gemma` | `copilot/gemma*`, `google/gemma*`, `gemini/gemma*` | | `deep-research` | `copilot/deep-research*`, `copilot/o3-deep-research*`, `copilot/o4-mini-deep-research*`, `google/deep-research*`, `gemini/deep-research*`, `openai/o3-deep-research*`, `openai/o4-mini-deep-research*` | | `fable` | `copilot/*fable*`, `anthropic/*fable*` | +| `auto` | `copilot/auto`, `large` | | `any` | `copilot/*`, `anthropic/*`, `openai/*`, `google/*`, `gemini/*` | | `gemini-3-pro` | `copilot/gemini-3*pro*`, `google/gemini-3*pro*`, `google/nano-banana*`, `gemini/gemini-3*pro*` | | `gemini-3-flash` | `copilot/gemini-3*flash*`, `google/gemini-3*flash*`, `gemini/gemini-3*flash*` | diff --git a/docs/src/content/docs/setup/creating-workflows.mdx b/docs/src/content/docs/setup/creating-workflows.mdx index 9014a56029c..5b5ec3bb2dd 100644 --- a/docs/src/content/docs/setup/creating-workflows.mdx +++ b/docs/src/content/docs/setup/creating-workflows.mdx @@ -9,6 +9,8 @@ import CopyEntireFileButton from '../../../components/CopyEntireFileButton.astro import Video from '../../../components/Video.astro'; import { Tabs, TabItem } from '@astrojs/starlight/components'; +An agentic workflow is a Markdown file in `.github/workflows/` that describes automation in natural language. The `gh aw compile` command turns it into a hardened GitHub Actions workflow that runs your chosen AI engine — Copilot, Claude, Codex, or Gemini — on a schedule or in response to repository events, with sandboxed execution and safe outputs controlling any writes back to GitHub. + **⏱️ Estimated time: 5-15 minutes** depending on complexity You can author new agentic workflows using a coding agent or other AI chat system, under your guidance. For interactive coding agents, this can be a conversation about what you want the workflow to do, with the agent asking clarifying questions and generating the workflow for you. diff --git a/docs/src/content/docs/setup/quick-start.mdx b/docs/src/content/docs/setup/quick-start.mdx index 28fd3cd25eb..a7e00555b37 100644 --- a/docs/src/content/docs/setup/quick-start.mdx +++ b/docs/src/content/docs/setup/quick-start.mdx @@ -1,13 +1,54 @@ --- title: Quick Start -description: Get your first agentic workflow running in minutes. Install the extension, add a sample workflow, set up secrets, and run your first AI-powered automation. +description: Get your first agentic workflow running in minutes. Install the gh-aw CLI extension, pick an AI engine (Copilot, Claude, Codex, or Gemini), add a workflow, and watch it run automatically in GitHub Actions. sidebar: order: 1 +head: + - tag: script + attrs: + type: application/ld+json + content: | + { + "@context": "https://schema.org", + "@type": "HowTo", + "name": "Set up GitHub Agentic Workflows in 10 minutes", + "description": "Install the gh-aw CLI extension, pick an AI engine, add a workflow, and watch it run automatically in GitHub Actions.", + "estimatedCost": { "@type": "MonetaryAmount", "currency": "USD", "value": "0" }, + "totalTime": "PT10M", + "step": [ + { + "@type": "HowToStep", + "name": "Install the gh-aw extension", + "text": "Run: gh extension install github/gh-aw", + "position": 1 + }, + { + "@type": "HowToStep", + "name": "Add a sample workflow and select an AI engine", + "text": "Run: gh aw add-wizard githubnext/agentics/daily-repo-status — then follow the interactive prompts to choose Copilot, Claude, Codex, or Gemini and set up the required secret.", + "position": 2 + }, + { + "@type": "HowToStep", + "name": "Wait for the workflow to complete", + "text": "After the workflow runs (2-3 minutes), a Daily Repo Report issue appears in your repository Issues tab.", + "position": 3 + }, + { + "@type": "HowToStep", + "name": "Customize your workflow (optional)", + "text": "Open .github/workflows/daily-repo-status.md, edit the instructions, run gh aw compile to regenerate the lock file, then commit and push both files.", + "position": 4 + } + ] + } --- import Video from '../../../components/Video.astro'; import { Tabs, TabItem } from '@astrojs/starlight/components'; +By the end of this guide you will have a live, recurring AI workflow running in GitHub Actions on your repository — using whichever AI engine you already have access to (GitHub Copilot, Claude Code, OpenAI Codex, or Google Gemini). The whole setup takes about 10 minutes and requires only the GitHub CLI. + ## Adding an Automated Daily Status Workflow to Your Repo **⏱️ Estimated time: 10 minutes** @@ -197,3 +238,12 @@ Continue learning with these resources: - [Creating Agentic Workflows](/gh-aw/setup/creating-workflows/) - [How Agentic Workflows Work](/gh-aw/introduction/how-they-work/) - [Frequently Asked Questions](/gh-aw/reference/faq/) + +## Related guides + +These use-case guides show specific workflow patterns built on the same foundation you just set up: + +- [AI Issue Triage on GitHub](/gh-aw/guides/ai-issue-triage/) — label, deduplicate, and ask clarifying questions on new issues automatically +- [Automated AI Pull Request Review](/gh-aw/guides/automated-pr-review/) — review diffs and post feedback comments when PRs are opened +- [AI-Generated Release Notes and Reports](/gh-aw/guides/ai-release-notes/) — generate release summaries and repo reports on a schedule +- [Keeping Documentation Up to Date Automatically](/gh-aw/guides/docs-automation/) — propose documentation updates as pull requests when code changes