Skip to content

Document Antigravity engine support in reference docs and schema guidance #42294

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

Closed
Copilot wants to merge 2 commits into from
+57 −16
Closed

Document Antigravity engine support in reference docs and schema guidance #42294

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
5bec3c0
Initial plan
Copilot Jun 29, 2026
19b9311
Document antigravity engine support
Copilot Jun 29, 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
24 changes: 24 additions & 0 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 @@ -37,6 +37,12 @@ Configure one GitHub Actions secret per engine before running your first workflo
- **Alternative:** None
- **Notes:** API key from Google AI Studio

### Antigravity

- **Required secret:** [`ANTIGRAVITY_API_KEY`](#antigravity_api_key)
- **Alternative:** None
- **Notes:** API key for the experimental Antigravity CLI engine

Most workflows will run without any additional secrets or additional authentication beyond this one engine secret.

## Additional Authentication
Expand Down Expand Up @@ -332,6 +338,24 @@ See also [AI Engines](/gh-aw/reference/engines/#available-coding-agents) for add

---

### `ANTIGRAVITY_API_KEY`

If using the Antigravity CLI engine, set a GitHub Actions secret `ANTIGRAVITY_API_KEY`.

**Setup**:

1. Obtain an API key for the Antigravity CLI account or environment you use.

2. Add it to your repository secrets, either by CLI or GitHub UI:

```bash wrap
gh aw secrets set ANTIGRAVITY_API_KEY --value "YOUR_ANTIGRAVITY_API_KEY"
```

See also [AI Engines](/gh-aw/reference/engines/#antigravity-cli) for additional configuration needed when using Antigravity in a workflow.

---

## Troubleshooting auth errors

Common authentication errors and how to resolve them:
Expand Down
40 changes: 26 additions & 14 deletions docs/src/content/docs/reference/engines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: AI Engines (aka Coding Agents)
description: Complete guide to AI engines (coding agents) usable with GitHub Agentic Workflows, including Copilot, Claude, Codex, Gemini, Crush, OpenCode, and Pi with their specific configuration options.
description: Complete guide to AI engines (coding agents) usable with GitHub Agentic Workflows, including Copilot, Claude, Codex, Gemini, Antigravity, Crush, OpenCode, and Pi with their specific configuration options.
sidebar:
order: 600
---
Expand All @@ -17,6 +17,7 @@ Set `engine:` in your workflow frontmatter and configure the corresponding secre
| [Claude by Anthropic (Claude Code)](https://www.anthropic.com/index/claude) | `claude` | [`ANTHROPIC_API_KEY`](/gh-aw/reference/auth/#anthropic_api_key) (standard) or [`engine.auth` Anthropic WIF](/gh-aw/reference/auth/#anthropic-workload-identity-federation-wif) (keyless) |
| [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) |
| [Antigravity CLI](https://antigravity.google/docs/cli-overview) (experimental) | `antigravity` | [ANTIGRAVITY_API_KEY](/gh-aw/reference/auth/#antigravity_api_key) |
| [Crush](https://github.com/charmbracelet/crush) (experimental) | `crush` | [COPILOT_GITHUB_TOKEN](/gh-aw/reference/auth/#copilot_github_token) |
| [OpenCode](https://opencode.ai) (experimental) | `opencode` | [COPILOT_GITHUB_TOKEN](/gh-aw/reference/auth/#copilot_github_token) |
| [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (experimental) | `pi` | [COPILOT_GITHUB_TOKEN](/gh-aw/reference/auth/#copilot_github_token) (default); switches to provider-specific secret when `model:` uses `provider/model` format |
Expand All @@ -25,24 +26,24 @@ Copilot CLI is the default — `engine:` can be omitted when using Copilot. See

## Which engine should I choose?

Choose the engine that best matches your needs and existing AI account: Copilot supports the broadest gh-aw feature set, including custom agents and autopilot-style continuations; Claude offers stronger control over turn limits (`max-turns`) for long reasoning sessions; and Gemini or Codex fit well when those models are already part of existing tooling or budget decisions. You can switch later by changing only `engine:` and the corresponding secret.
Choose the engine that best matches your needs and existing AI account: Copilot supports the broadest gh-aw feature set, including custom agents and autopilot-style continuations; Claude offers stronger control over turn limits (`max-turns`) for long reasoning sessions; Gemini or Codex fit well when those models are already part of existing tooling or budget decisions; and Antigravity is a fit when you want the experimental Google CLI runtime with headless mode and AWF LLM gateway integration. You can switch later by changing only `engine:` and the corresponding secret.

## Engine Feature Comparison

Not all features are available across all engines. The table below summarizes per-engine support for commonly used workflow options:

| Feature | Copilot | Claude | Codex | Gemini | Crush | OpenCode | Pi |
|---------|:-------:|:------:|:-----:|:------:|:-----:|:--------:|:--:|
| `max-turns` (AWF invocation cap; `max-runs` deprecated) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `max-turns` | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `max-continuations` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `tools.web-fetch` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `tools.web-search` | via MCP | via MCP | ✅ (opt-in) | via MCP | via MCP | via MCP | via MCP |
| `engine.agent` (custom agent file) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `engine.api-target` (custom endpoint) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `engine.bare` (disable context loading) | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
| `engine.harness` (custom harness script) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Tools allowlist | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
| Feature | Copilot | Claude | Codex | Gemini | Antigravity | Crush | OpenCode | Pi |
|---------|:-------:|:------:|:-----:|:------:|:------------:|:-----:|:--------:|:--:|
| `max-turns` (AWF invocation cap; `max-runs` deprecated) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `max-turns` | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `max-continuations` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `tools.web-fetch` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `tools.web-search` | via MCP | via MCP | ✅ (opt-in) | via MCP | via MCP | via MCP | via MCP | via MCP |
| `engine.agent` (custom agent file) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `engine.api-target` (custom endpoint) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `engine.bare` (disable context loading) | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `engine.harness` (custom harness script) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Tools allowlist | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |

`max-turns` (default `500`, legacy alias `max-runs`) and `max-ai-credits` (default `1000`) are top-level frontmatter fields supported by all engines. `engine.max-turns` is a deprecated nested alias that still limits Claude iterations when present; `max-continuations` enables Copilot autopilot mode. Codex `web-search` is opt-in via `tools: web-search:`; other engines use a third-party MCP server — see [Using Web Search](/gh-aw/reference/web-search/). `engine.agent`, `engine.bare`, and `engine.harness` are described below.

Expand Down Expand Up @@ -71,6 +72,7 @@ By default, workflows install the latest available version of each engine CLI. T
| Claude Code | `claude` | `"2.1.70"` |
| Codex | `codex` | `"0.111.0"` |
| Gemini CLI | `gemini` | `"0.31.0"` |
| Antigravity CLI | `antigravity` | `"1.0.2-6113393518706688"` |
| Crush | `crush` | `"1.2.14"` |
| OpenCode | `opencode` | `"0.1.0"` |
| Pi | `pi` | `"0.72.1"` |
Expand Down Expand Up @@ -100,6 +102,16 @@ engine:
version: ${{ inputs.engine-version }}
```

### Antigravity CLI

Use `antigravity` to run the experimental Antigravity CLI with AWF-managed headless execution and LLM gateway integration. Configure `ANTIGRAVITY_API_KEY`, and use an MCP server when the workflow needs web search because Antigravity does not provide a built-in `web-search` tool.

```yaml wrap
engine:
id: antigravity
version: "1.0.2-6113393518706688"
```

### Copilot Custom Configuration

Use `agent` to reference a custom agent file in `.github/agents/` (omit the `.agent.md` extension):
Expand Down
9 changes: 7 additions & 2 deletions pkg/parser/schemas/main_workflow_schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11761,8 +11761,13 @@
},
"engine_config": {
"examples": [
"antigravity",
"claude",
"copilot",
{
"id": "antigravity",
"version": "1.0.2-6113393518706688"
},
{
"id": "claude",
"model": "claude-3-5-sonnet-20241022",
Expand Down Expand Up @@ -11836,15 +11841,15 @@
"oneOf": [
{
"type": "string",
"description": "Engine name: built-in ('claude', 'codex', 'copilot', 'gemini', 'opencode', 'crush', 'pi') or a named catalog entry"
"description": "Engine name: built-in ('antigravity', 'claude', 'codex', 'copilot', 'gemini', 'opencode', 'crush', 'pi') or a named catalog entry"
},
{
"type": "object",
"description": "Extended engine configuration object with advanced options for model selection, turn limiting, environment variables, and custom steps",
"properties": {
"id": {
"type": "string",
"description": "AI engine identifier: built-in ('claude', 'codex', 'copilot', 'gemini', 'opencode', 'crush', 'pi') or a named catalog entry"
"description": "AI engine identifier: built-in ('antigravity', 'claude', 'codex', 'copilot', 'gemini', 'opencode', 'crush', 'pi') or a named catalog entry"
},
"version": {
"type": ["string", "number"],
Expand Down