diff --git a/docs/src/content/docs/guides/getting-started-mcp.md b/docs/src/content/docs/guides/getting-started-mcp.md index 1aac07d01e7..4752bf7bb78 100644 --- a/docs/src/content/docs/guides/getting-started-mcp.md +++ b/docs/src/content/docs/guides/getting-started-mcp.md @@ -5,11 +5,11 @@ sidebar: order: 2 --- -This guide walks you through integrating Model Context Protocol (MCP) servers with GitHub Agentic Workflows, from your first configuration to advanced patterns. +This guide walks you through integrating [Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP) servers with GitHub Agentic Workflows, from your first configuration to advanced patterns. ## What is MCP? -Model Context Protocol (MCP) is a standardized protocol that enables AI agents to connect to external tools, databases, and APIs. MCP servers act as specialized adapters, giving agents access to GitHub, web search, databases, and third-party services like Notion, Slack, and Datadog. +[Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP) is a standardized protocol that enables AI [agents](/gh-aw/reference/glossary/#agent) (autonomous AI systems) to connect to external tools, databases, and APIs. [MCP servers](/gh-aw/reference/glossary/#mcp-server) act as specialized adapters, giving agents access to GitHub, web search, databases, and third-party services like Notion, Slack, and Datadog. ## Quick Start @@ -37,7 +37,7 @@ tools: Analyze the issue and provide a summary of similar existing issues. ``` -The `toolsets: [default]` configuration gives your agent access to repository, issue, and pull request tools. +The `toolsets: [default]` configuration gives your [agent](/gh-aw/reference/glossary/#agent) (the AI system executing the workflow) access to repository, issue, and pull request tools. ### Step 2: Compile and Test @@ -53,7 +53,7 @@ Verify the MCP configuration: gh aw mcp inspect my-workflow ``` -You now have a working MCP integration. The agent can read issues, search repositories, and access pull request information. +You now have a working MCP integration. The [agent](/gh-aw/reference/glossary/#agent) can read issues, search repositories, and access pull request information. ## Configuration Patterns diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 167f04ffbe7..cf4c02a7418 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -44,7 +44,7 @@ import FeatureGrid from '../../components/FeatureGrid.astro'; ## What is GitHub Agentic Workflows? -GitHub Agentic Workflows transforms how you automate your repository. Instead of writing complex YAML configurations, you describe your automation goals in plain markdown. AI agents then execute these workflows safely with built-in security controls, making intelligent decisions based on context. +GitHub Agentic Workflows transforms how you automate your repository. Instead of writing complex YAML configurations, you describe your automation goals in plain markdown. AI [agents](/gh-aw/reference/glossary/#agent) (autonomous AI systems that can understand and execute instructions) then execute these workflows safely with built-in security controls, making intelligent decisions based on context. **Perfect for:** - 🤖 **Issue triage** - Automatically categorize, label, and respond to new issues @@ -52,7 +52,7 @@ GitHub Agentic Workflows transforms how you automate your repository. Instead of - 🔧 **Repository maintenance** - Automate dependency updates, documentation, and cleanup tasks **Security built-in:** -Workflows run with read-only permissions by default. Write operations require explicit approval through sanitized safe-outputs, with sandboxed execution, tool allowlisting, and network isolation ensuring AI agents operate safely within controlled boundaries. +Workflows run with read-only permissions by default. Write operations require explicit approval through sanitized [safe outputs](/gh-aw/reference/glossary/#safe-outputs) (pre-approved GitHub operations), with sandboxed execution, tool allowlisting, and network isolation ensuring AI agents operate safely within controlled boundaries. ## Key Features diff --git a/docs/src/content/docs/introduction/how-it-works.mdx b/docs/src/content/docs/introduction/how-it-works.mdx index 628e70f08d5..5ac6c6dd0f7 100644 --- a/docs/src/content/docs/introduction/how-it-works.mdx +++ b/docs/src/content/docs/introduction/how-it-works.mdx @@ -5,11 +5,11 @@ sidebar: order: 2 --- -GitHub Agentic Workflows enable AI [agents](/gh-aw/reference/glossary/#agent) (autonomous AI systems that can make decisions) to perform complex, multi-step tasks automatically with your team. Built on [GitHub Actions](https://docs.github.com/en/actions), they use [**GitHub Copilot**](/gh-aw/reference/engines/#github-copilot-cli) (or experimental engines like Claude and Codex) to interpret natural language instructions and enable [Continuous AI](https://githubnext.com/projects/continuous-ai) — systematic, automated application of AI to software collaboration. +GitHub Agentic Workflows enable AI [agents](/gh-aw/reference/glossary/#agent) (autonomous AI systems that can make decisions) to perform complex, multi-step tasks automatically with your team. Built on [GitHub Actions](https://docs.github.com/en/actions), they use [**GitHub Copilot**](/gh-aw/reference/engines/#github-copilot-cli) (or experimental [engines](/gh-aw/reference/glossary/#engine), which are AI models/providers like Claude and Codex) to interpret natural language instructions and enable [Continuous AI](https://githubnext.com/projects/continuous-ai) — systematic, automated application of AI to software collaboration. ## Workflow Structure -Each workflow contains [frontmatter](/gh-aw/reference/glossary/#frontmatter) (YAML configuration section) and markdown instructions. The frontmatter defines [triggers](/gh-aw/reference/triggers/), [permissions](/gh-aw/reference/permissions/), and [tools](/gh-aw/reference/tools/), while the markdown contains natural language task descriptions. This declarative structure enables reliable, secure agentic programming by sandboxing AI capabilities and triggering at the right moments. +Each workflow contains [frontmatter](/gh-aw/reference/glossary/#frontmatter) (the YAML configuration section between `---` markers) and markdown instructions. The frontmatter defines [triggers](/gh-aw/reference/triggers/) (when the workflow runs), [permissions](/gh-aw/reference/permissions/) (what it can access), and [tools](/gh-aw/reference/tools/) (what capabilities the AI has), while the markdown contains natural language task descriptions. This declarative structure enables reliable, secure agentic programming by sandboxing AI capabilities and triggering at the right moments. ```aw warp --- @@ -27,13 +27,13 @@ Workflows support **GitHub Copilot** (default), **Claude Code**, and **Codex**. ## Tools and Model Context Protocol (MCP) -Workflows use [tools](/gh-aw/reference/tools/) through the **[Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol)** (MCP, a standard for AI tool integration) — a standardized protocol for connecting AI agents to external tools and services — for GitHub operations, external APIs, file operations, and custom integrations. +Workflows use [tools](/gh-aw/reference/tools/) through the **[Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol)** (MCP, a standardized protocol for connecting AI agents to external tools and services) for GitHub operations, external APIs, file operations, and custom integrations. ## Agentic vs. Traditional Workflows **Traditional workflows** execute pre-programmed steps with fixed if/then logic. They do exactly what you tell them, every time, in the same way. -**[Agentic workflows](/gh-aw/reference/glossary/#agentic)** use AI to understand context, make decisions, and generate content by interpreting natural language instructions flexibly. They combine deterministic GitHub Actions infrastructure with AI-driven decision-making, adapting their behavior based on the specific situation they encounter. +**[Agentic workflows](/gh-aw/reference/glossary/#agentic)** (workflows that have agency—the ability to make autonomous decisions) use AI to understand context, make decisions, and generate content by interpreting natural language instructions flexibly. They combine deterministic GitHub Actions infrastructure with AI-driven decision-making, adapting their behavior based on the specific situation they encounter. ## Security Design @@ -57,7 +57,7 @@ Workflows run with minimal permissions (no write access by default), use tool al ## Compilation -Use `gh aw compile` to generate `.lock.yml` files (compiled GitHub Actions workflow files) from workflow `.md` files. The `.md` file is the editable source of truth, while `.lock.yml` is the compiled GitHub Actions workflow with security hardening. Commit both files. +Use `gh aw compile` to generate [`.lock.yml` files](/gh-aw/reference/glossary/#workflow-lock-file-lockyml) (compiled GitHub Actions workflow files) from workflow `.md` files. The `.md` file is the editable source of truth, while `.lock.yml` is the compiled GitHub Actions workflow with security hardening. Commit both files. ## Continuous AI Patterns @@ -65,4 +65,4 @@ Enable [Continuous AI](https://githubnext.com/projects/continuous-ai) patterns l ## Best Practices -Start simple and iterate with clear, specific instructions. Test workflows using `gh aw compile --watch` and `gh aw run`, monitor costs with `gh aw logs`, and review AI-generated content before merging. Use [`safe outputs`](/gh-aw/reference/safe-outputs/) (validated GitHub operations) for controlled creation of issues, comments, and PRs. +Start simple and iterate with clear, specific instructions. Test workflows using `gh aw compile --watch` and `gh aw run`, monitor costs with `gh aw logs`, and review AI-generated content before merging. Use [`safe outputs`](/gh-aw/reference/safe-outputs/) (pre-approved GitHub operations) for controlled creation of issues, comments, and PRs. diff --git a/docs/src/content/docs/introduction/overview.mdx b/docs/src/content/docs/introduction/overview.mdx index fa7ea0226f3..2123e94a067 100644 --- a/docs/src/content/docs/introduction/overview.mdx +++ b/docs/src/content/docs/introduction/overview.mdx @@ -7,16 +7,16 @@ sidebar: ## What are Agentic Workflows? -**Agentic workflows** are AI-powered automation that can understand context, make decisions, and take meaningful actions—all from natural language instructions you write in markdown. +**[Agentic workflows](/gh-aw/reference/glossary/#agentic-workflow)** (AI-powered workflows that can make decisions and adapt to situations) are AI-powered automation that can understand context, make decisions, and take meaningful actions—all from natural language instructions you write in markdown. -Unlike traditional automation with fixed if-then rules, agentic workflows use AI [agents](/gh-aw/reference/glossary/#agent) (AI systems that execute instructions) like GitHub Copilot to: +Unlike traditional automation with fixed if-then rules, agentic workflows use AI [agents](/gh-aw/reference/glossary/#agent) (AI systems that execute your instructions) like GitHub Copilot to: - **Understand context**: Read your repository, issues, and pull requests to grasp the current situation - **Make decisions**: Choose appropriate actions based on the context, not just predefined conditions - **Adapt behavior**: Respond flexibly to different scenarios without requiring explicit programming for each case ## Natural Language to GitHub Actions -Imagine describing your automation needs in plain language instead of wrestling with complex YAML syntax and API calls. GitHub Agentic Workflows makes this possible by transforming natural language markdown files into [GitHub Actions](https://github.com/features/actions) that are executed by AI [agents](/gh-aw/reference/glossary/#agent) (AI systems that execute instructions). +Imagine describing your automation needs in plain language instead of wrestling with complex YAML syntax and API calls. GitHub Agentic Workflows makes this possible by transforming natural language markdown files into [GitHub Actions](https://github.com/features/actions) that are executed by AI [agents](/gh-aw/reference/glossary/#agent) (AI systems that execute your instructions). Instead of writing intricate scripts to handle issue triage, code reviews, or release management, you simply describe what you want to happen. The AI agent understands your repository context, interprets the situation, and takes appropriate actions—all from a few lines of markdown. @@ -36,7 +36,7 @@ safe-outputs: Analyze the current issue and ask for additional details if the issue is unclear. ``` -The `gh aw compile` command transforms this markdown into a secure [GitHub Actions Workflow](https://docs.github.com/en/actions/concepts/workflows-and-actions/workflows#about-workflows) (`.lock.yml` file) that runs an AI agent in a containerized environment whenever a new issue is opened. +The `gh aw compile` command transforms this markdown into a secure [GitHub Actions Workflow](https://docs.github.com/en/actions/concepts/workflows-and-actions/workflows#about-workflows) ([`.lock.yml` file](/gh-aw/reference/glossary/#workflow-lock-file-lockyml), the compiled workflow that GitHub Actions runs) that runs an AI agent in a containerized environment whenever a new issue is opened. [Compilation](/gh-aw/reference/glossary/#compilation) (converting markdown to GitHub Actions YAML) validates your configuration, applies security hardening, and generates the final workflow file that GitHub Actions can execute. Think of it like compiling code—you write human-friendly markdown, the compiler produces machine-ready YAML. diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md index 3c7d44f4ca4..fe410f68dc7 100644 --- a/docs/src/content/docs/reference/engines.md +++ b/docs/src/content/docs/reference/engines.md @@ -5,7 +5,7 @@ sidebar: order: 600 --- -GitHub Agentic Workflows support multiple AI [engines](/gh-aw/reference/glossary/#engine) (AI model/provider) to interpret and execute natural language instructions. Each engine has unique capabilities and configuration options. +GitHub Agentic Workflows support multiple AI [engines](/gh-aw/reference/glossary/#engine) (which AI model/provider to use) to interpret and execute natural language instructions. Each engine has unique capabilities and configuration options. :::note[Experimental Engines] Claude and Codex engines are available but marked as experimental. They are not documented here but can still be used by setting `engine: claude` or `engine: codex` in your workflow frontmatter. For production workflows, we recommend using the GitHub Copilot CLI engine. @@ -13,7 +13,7 @@ Claude and Codex engines are available but marked as experimental. They are not ### GitHub Copilot CLI -GitHub Copilot is the default and recommended AI engine for most workflows. The [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli) provides [Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP) server support and is designed for conversational AI workflows. +GitHub Copilot is the default and recommended AI [engine](/gh-aw/reference/glossary/#engine) (which AI model/provider to use) for most workflows. The [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli) provides [Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP, the standardized protocol for connecting AI agents to tools) server support and is designed for conversational AI workflows. ```yaml wrap engine: copilot @@ -33,7 +33,7 @@ Configuration options: `model` (gpt-5 or claude-sonnet-4), `version` (CLI versio #### Required Secrets -**`COPILOT_GITHUB_TOKEN`**: GitHub Personal Access Token (PAT) with "Copilot Requests" permission. **`GH_AW_GITHUB_TOKEN`** (optional): Required for [GitHub Tools Remote Mode](/gh-aw/reference/tools/#modes-and-restrictions). +**`COPILOT_GITHUB_TOKEN`**: GitHub [Personal Access Token](/gh-aw/reference/glossary/#personal-access-token-pat) (PAT, a token that authenticates you to GitHub's APIs) with "Copilot Requests" permission. **`GH_AW_GITHUB_TOKEN`** (optional): Required for [GitHub Tools Remote Mode](/gh-aw/reference/tools/#modes-and-restrictions). #### Authenticating with a Personal Access Token (PAT) diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md index abc1a8ff04b..0f209f40f88 100644 --- a/docs/src/content/docs/reference/frontmatter.md +++ b/docs/src/content/docs/reference/frontmatter.md @@ -5,7 +5,7 @@ sidebar: order: 200 --- -The [frontmatter](/gh-aw/reference/glossary/#frontmatter) (YAML configuration section) of GitHub Agentic Workflows includes the triggers, permissions, AI engines, and workflow settings. For example: +The [frontmatter](/gh-aw/reference/glossary/#frontmatter) (YAML configuration section between `---` markers) of GitHub Agentic Workflows includes the triggers, permissions, AI [engines](/gh-aw/reference/glossary/#engine) (which AI model/provider to use), and workflow settings. For example: ```yaml wrap --- @@ -24,7 +24,7 @@ tools: The frontmatter combines standard GitHub Actions properties (`on`, `permissions`, `run-name`, `runs-on`, `timeout-minutes`, `concurrency`, `env`, `environment`, `container`, `services`, `if`, `steps`, `cache`) with GitHub Agentic Workflows-specific elements (`description`, `source`, `github-token`, `imports`, `engine`, `strict`, `roles`, `features`, `safe-inputs`, `safe-outputs`, `network`, `tools`). -Tool configurations (such as `bash`, `edit`, `github`, `web-fetch`, `web-search`, `playwright`, `cache-memory`, and custom [Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP) servers) are specified under the `tools:` key. Custom inline tools can be defined with the [`safe-inputs:`](/gh-aw/reference/safe-inputs/) (validated user input tools) key. See [Tools](/gh-aw/reference/tools/) and [Safe Inputs](/gh-aw/reference/safe-inputs/) for complete documentation. +Tool configurations (such as `bash`, `edit`, `github`, `web-fetch`, `web-search`, `playwright`, `cache-memory`, and custom [Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP) [servers](/gh-aw/reference/glossary/#mcp-server)) are specified under the `tools:` key. Custom inline tools can be defined with the [`safe-inputs:`](/gh-aw/reference/safe-inputs/) (custom tools defined inline) key. See [Tools](/gh-aw/reference/tools/) and [Safe Inputs](/gh-aw/reference/safe-inputs/) for complete documentation. ### Trigger Events (`on:`) diff --git a/docs/src/content/docs/reference/glossary.md b/docs/src/content/docs/reference/glossary.md index 85842673cb4..f49534ddc07 100644 --- a/docs/src/content/docs/reference/glossary.md +++ b/docs/src/content/docs/reference/glossary.md @@ -7,6 +7,10 @@ sidebar: This glossary provides definitions for key technical terms and concepts used in GitHub Agentic Workflows. +:::tip[New to GitHub Agentic Workflows?] +Technical terms throughout the documentation link to their definitions here. Click any glossary link to understand unfamiliar concepts. Bookmark this page for quick reference! +::: + ## Core Concepts ### Agentic @@ -125,9 +129,12 @@ safe-outputs: ## Workflow Components ### Engine -The AI system that powers the agentic workflow. GitHub Agentic Workflows supports multiple engines: + +The AI system that powers the [agentic workflow](#agentic-workflow). GitHub Agentic Workflows supports multiple engines: - **GitHub Copilot** (default): Uses GitHub's coding assistant +An engine is essentially "which AI to use"—think of it as choosing between different AI assistants (like Copilot, Claude, or others) to execute your workflow instructions. + ### Triggers Events that cause a workflow to run. Defined in the `on:` section of frontmatter. Includes issue events (`issues:`), pull request events (`pull_request:`), scheduled runs (`schedule:`), manual runs (`workflow_dispatch:`), and comment commands (`slash_command:`). diff --git a/docs/src/content/docs/setup/quick-start.md b/docs/src/content/docs/setup/quick-start.md index ddd2095065d..6bad43f3cc6 100644 --- a/docs/src/content/docs/setup/quick-start.md +++ b/docs/src/content/docs/setup/quick-start.md @@ -7,7 +7,7 @@ sidebar: > [!WARNING] > **GitHub Agentic Workflows** is a *research demonstrator* in early development and may change significantly. -> Using [agentic workflows](/gh-aw/reference/glossary/#agentic-workflow) means giving AI [agents](/gh-aw/reference/glossary/#agent) (autonomous AI systems) the ability to make decisions and take actions in your repository. This requires careful attention to security considerations and human supervision. +> Using [agentic workflows](/gh-aw/reference/glossary/#agentic-workflow) (AI-powered workflows that can make autonomous decisions) means giving AI [agents](/gh-aw/reference/glossary/#agent) (autonomous AI systems) the ability to make decisions and take actions in your repository. This requires careful attention to security considerations and human supervision. > Review all outputs carefully and use time-limited trials to evaluate effectiveness for your team. ## Prerequisites @@ -52,9 +52,9 @@ Before installing anything, it helps to understand the workflow lifecycle: ``` **Why two files?** -- **`.md` file**: Human-friendly markdown with natural language instructions and simple YAML configuration. This is what you write and edit. +- **`.md` file**: Human-friendly markdown with natural language instructions and simple YAML [frontmatter](/gh-aw/reference/glossary/#frontmatter) (configuration at the top between `---` markers). This is what you write and edit. - **[`.lock.yml` file](/gh-aw/reference/glossary/#workflow-lock-file-lockyml)**: Machine-ready GitHub Actions YAML with security hardening applied. This is what GitHub Actions runs. -- **Compilation**: The `gh aw compile` command translates your markdown into validated, secure GitHub Actions YAML. +- **[Compilation](/gh-aw/reference/glossary/#compilation)**: The `gh aw compile` command translates your markdown into validated, secure GitHub Actions YAML. Think of it like writing code in a high-level language (Python, JavaScript) that gets compiled to machine code. You write natural language, GitHub runs the compiled workflow. @@ -88,11 +88,11 @@ Add a sample from the [agentics](https://github.com/githubnext/agentics) collect gh aw add githubnext/agentics/daily-team-status --create-pull-request ``` -This creates a pull request that adds `.github/workflows/daily-team-status.md` and the [compiled](/gh-aw/reference/glossary/#compilation) `.lock.yml` (the generated GitHub Actions workflow file). Review and merge the PR into your repo. +This creates a pull request that adds `.github/workflows/daily-team-status.md` and the [compiled](/gh-aw/reference/glossary/#compilation) (translated from markdown to GitHub Actions YAML) `.lock.yml` (the generated GitHub Actions workflow file). Review and merge the PR into your repo. ### Step 3 — Add an AI secret -Agentic workflows need to authenticate with an AI service to execute your natural language instructions. By default, they use **GitHub Copilot** as the [coding agent](/gh-aw/reference/glossary/#agent) (the AI system that executes your instructions). +[Agentic workflows](/gh-aw/reference/glossary/#agentic-workflow) (AI-powered workflows) need to authenticate with an AI service to execute your natural language instructions. By default, they use **GitHub Copilot** as the [coding agent](/gh-aw/reference/glossary/#agent) (the AI system that executes your instructions). To allow your workflows to use Copilot, you'll create a token and add it as a repository secret. @@ -166,7 +166,7 @@ Once complete, a new issue will be created in your repository with daily news! T ## Understanding Your First Workflow The daily team status workflow creates a status report every weekday and posts it as an issue. The workflow file has two parts: -- **[Frontmatter](/gh-aw/reference/glossary/#frontmatter)** (YAML configuration section) — The section between `---` markers that configures when the workflow runs and what it can do +- **[Frontmatter](/gh-aw/reference/glossary/#frontmatter)** (YAML configuration section between `---` markers) — Configures when the workflow runs and what it can do - **Markdown instructions** — Natural language task descriptions for the AI ```aw wrap @@ -201,8 +201,8 @@ Create an upbeat daily status report for the team as a GitHub issue. ``` **Key configuration elements:** -- **[`tools:`](/gh-aw/reference/tools/)** — Capabilities the AI can use (GitHub API access) -- **[`safe-outputs:`](/gh-aw/reference/safe-outputs/)** (validated GitHub API operations) — Allows creating issues without giving the AI write permissions +- **[`tools:`](/gh-aw/reference/tools/)** — Capabilities the AI can use (like GitHub API access) +- **[`safe-outputs:`](/gh-aw/reference/safe-outputs/)** (pre-approved GitHub operations) — Allows creating issues without giving the AI write permissions ## Customize Your Workflow