Skip to content

[docs] docs: consolidate repetitive engine sections in engines.md #19779

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Mar 6, 2026
Merged

[docs] docs: consolidate repetitive engine sections in engines.md #19779

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cd869b6
docs: consolidate repetitive engine sections in engines.md
actions-user Mar 6, 2026
eb172bb
ci: trigger checks
github-actions[bot] Mar 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/src/content/docs/reference/auth.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ If using the Claude by Anthropic engine, you need to set a GitHub Actions secret
gh aw secrets set ANTHROPIC_API_KEY --value "YOUR_ANTHROPIC_API_KEY"
```

See also [Using Claude Code](/gh-aw/reference/engines/#using-claude-by-anthropic-claude-code) for additional configuration needed when using Claude with GitHub MCP.
See also [AI Engines](/gh-aw/reference/engines/#available-coding-agents) for additional configuration needed when using Claude with GitHub MCP.

---

Expand All @@ -127,7 +127,7 @@ If using the Codex by OpenAI engine, you need to set a GitHub Actions secret `OP
gh aw secrets set OPENAI_API_KEY --value "YOUR_OPENAI_API_KEY"
```

See also [Using Codex](/gh-aw/reference/engines/#using-openai-codex) for additional configuration needed when using Codex with GitHub MCP.
See also [AI Engines](/gh-aw/reference/engines/#available-coding-agents) for additional configuration needed when using Codex with GitHub MCP.

---

Expand All @@ -145,7 +145,7 @@ If using the Gemini by Google engine, you need to set a GitHub Actions secret `G
gh aw secrets set GEMINI_API_KEY --value "YOUR_GEMINI_API_KEY"
```

See also [Using Gemini](/gh-aw/reference/engines/#using-google-gemini-cli) for additional configuration needed when using Gemini with GitHub MCP.
See also [AI Engines](/gh-aw/reference/engines/#available-coding-agents) for additional configuration needed when using Gemini with GitHub MCP.
Copy link

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This “See also” line implies the AI Engines page includes “additional configuration needed when using Gemini with GitHub MCP”, but the engines page doesn’t describe MCP-specific setup anymore. Please either link directly to the MCP/Tools docs that cover the configuration, or soften the wording to match what the target page actually contains.

This issue also appears in the following locations of the same file:

  • line 112
  • line 130

Copilot uses AI. Check for mistakes.

---

Expand Down
66 changes: 10 additions & 56 deletions docs/src/content/docs/reference/engines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,64 +5,20 @@ sidebar:
order: 600
---

GitHub Agentic Workflows use [AI Engines](/gh-aw/reference/glossary/#engine) (normally a coding agent) to interpret and execute natural language instructions. Each coding agent has unique capabilities and configuration options.
GitHub Agentic Workflows use [AI Engines](/gh-aw/reference/glossary/#engine) (normally a coding agent) to interpret and execute natural language instructions.

## Available Coding Agents

- [**Copilot CLI**](#using-copilot-cli)
- [**Claude by Anthropic (Claude Code)**](#using-claude-by-anthropic-claude-code)
- [**OpenAI Codex**](#using-openai-codex)
- [**Google Gemini CLI**](#using-google-gemini-cli)
Set `engine:` in your workflow frontmatter and configure the corresponding secret:

Comment on lines +12 to 13
Copy link

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The guidance is slightly self-contradictory: it says to set engine: in workflow frontmatter, but a few lines later notes engine: can be omitted for Copilot (the default). Consider rephrasing to clarify that engine: is optional and only required when selecting a non-default engine, while the secret still must be configured.

Copilot uses AI. Check for mistakes.
## Using Copilot CLI
| Engine | `engine:` value | Required Secret |
|--------|-----------------|-----------------|
| [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli) (default) | `copilot` | [COPILOT_GITHUB_TOKEN](/gh-aw/reference/auth/#copilot_github_token) |
| [Claude by Anthropic (Claude Code)](https://www.anthropic.com/index/claude) | `claude` | [ANTHROPIC_API_KEY](/gh-aw/reference/auth/#anthropic_api_key) |
| [OpenAI Codex](https://openai.com/blog/openai-codex) | `codex` | [OPENAI_API_KEY](/gh-aw/reference/auth/#openai_api_key) |
| [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) | `gemini` | [GEMINI_API_KEY](/gh-aw/reference/auth/#gemini_api_key) |

[GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli) is the default AI engine (coding agent).

To use Copilot CLI with GitHub Agentic Workflows:

1. Copilot CLI is the default AI engine (coding agent). You can optionally request the use of the Copilot CLI in your workflow frontmatter:

```yaml wrap
engine: copilot
```

2. Configure the `COPILOT_GITHUB_TOKEN` secret. See [Authentication: COPILOT_GITHUB_TOKEN](/gh-aw/reference/auth/#copilot_github_token) for setup instructions.

## Using Claude by Anthropic (Claude Code)

To use [Claude by Anthropic](https://www.anthropic.com/index/claude) (aka Claude Code):

1. Request the use of the Claude by Anthropic engine in your workflow frontmatter:

```yaml wrap
engine: claude
```

2. Configure the `ANTHROPIC_API_KEY` secret. See [Authentication: ANTHROPIC_API_KEY](/gh-aw/reference/auth/#anthropic_api_key) for setup instructions.

## Using OpenAI Codex

To use [OpenAI Codex](https://openai.com/blog/openai-codex):

1. Request the use of the Codex engine in your workflow frontmatter:

```yaml wrap
engine: codex
```

2. Configure the `OPENAI_API_KEY` secret. See [Authentication: OPENAI_API_KEY](/gh-aw/reference/auth/#openai_api_key) for setup instructions.

## Using Google Gemini CLI

To use [Google Gemini CLI](https://github.com/google-gemini/gemini-cli):

1. Request the use of the Gemini engine in your workflow frontmatter:

```yaml wrap
engine: gemini
```

2. Configure the `GEMINI_API_KEY` secret. See [Authentication: GEMINI_API_KEY](/gh-aw/reference/auth/#gemini_api_key) for setup instructions.
Copilot CLI is the default — `engine:` can be omitted when using Copilot. See the linked authentication docs for secret setup instructions.

## Extended Coding Agent Configuration

Expand Down Expand Up @@ -117,7 +73,7 @@ engine:
args: ["--add-dir", "/workspace", "--verbose"]
```

Arguments are added in order and placed before the `--prompt` flag. Common uses include adding directories (`--add-dir`), enabling verbose logging (`--verbose`, `--debug`), and passing engine-specific flags. Consult the specific engine's CLI documentation for available flags.
Arguments are added in order and placed before the `--prompt` flag. Consult the specific engine's CLI documentation for available flags.

### Custom Engine Command

Expand All @@ -130,8 +86,6 @@ engine:
args: ["--verbose"]
```

The command supports absolute paths (`/usr/local/bin/copilot`), relative paths (`./bin/claude`), environment variables (`$HOME/.local/bin/codex`), or commands in PATH.

## Related Documentation

- [Frontmatter](/gh-aw/reference/frontmatter/) - Complete configuration reference
Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/reference/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,7 @@ When using **GitHub Copilot CLI**, a Personal Access Token (PAT) with "Copilot R

### Can I use `CLAUDE_CODE_OAUTH_TOKEN` with the Claude engine?

No. `CLAUDE_CODE_OAUTH_TOKEN` is not supported by GitHub Agentic Workflows. The only supported authentication method for the Claude engine is [`ANTHROPIC_API_KEY`](/gh-aw/reference/auth/#anthropic_api_key), which must be configured as a GitHub Actions secret. Provider-based OAuth authentication for Claude (such as billing through a Claude Teams subscription) is not supported. See [Authentication](/gh-aw/reference/auth/) and [AI Engines](/gh-aw/reference/engines/#using-claude-by-anthropic-claude-code) for setup instructions.
No. `CLAUDE_CODE_OAUTH_TOKEN` is not supported by GitHub Agentic Workflows. The only supported authentication method for the Claude engine is [`ANTHROPIC_API_KEY`](/gh-aw/reference/auth/#anthropic_api_key), which must be configured as a GitHub Actions secret. Provider-based OAuth authentication for Claude (such as billing through a Claude Teams subscription) is not supported. See [Authentication](/gh-aw/reference/auth/) and [AI Engines](/gh-aw/reference/engines/#available-coding-agents) for setup instructions.

### What hidden runtime dependencies does this have?

Expand Down