Skip to content

[docs] docs(engines): reduce bloat in AI engines reference #25010

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 1 commit into from
Apr 7, 2026
Merged

[docs] docs(engines): reduce bloat in AI engines reference #25010

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
42 changes: 10 additions & 32 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 @@ -59,26 +59,17 @@ engine:

By default, workflows install the latest available version of each engine CLI. To pin to a specific version, set `version` to the desired release:

| Engine | `id` | Example `version` |
|--------|------|-------------------|
| GitHub Copilot CLI | `copilot` | `"0.0.422"` |
| Claude Code | `claude` | `"2.1.70"` |
| Codex | `codex` | `"0.111.0"` |
| Gemini CLI | `gemini` | `"0.31.0"` |
Comment on lines +64 to +67
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

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

In the version pinning table, the Example version cells include backslashes (e.g., \"0.0.422\"). Inside inline code, quotes don’t need escaping, so the backslashes will render literally and look wrong. Remove the backslashes so the table shows the version string as "0.0.422" (without backslashes).

Copilot uses AI. Check for mistakes.

```yaml wrap
# Pin Copilot CLI to a specific release
engine:
id: copilot
version: "0.0.422"

# Pin Claude Code to a specific release
engine:
id: claude
version: "2.1.70"

# Pin Codex to a specific release
engine:
id: codex
version: "0.111.0"

# Pin Gemini CLI to a specific release
engine:
id: gemini
version: "0.31.0"
```

Pinning is useful when you need reproducible builds or want to avoid breakage from a new CLI release while testing. Remember to update the pinned version periodically to pick up bug fixes and new features.
Expand All @@ -102,17 +93,15 @@ engine:

### Copilot Custom Configuration

For the Copilot engine, you can specify a specialized prompt to be used whenever the coding agent is invoked. This is called a "custom agent" in Copilot vocabulary. You specify this using the `agent` field. This references a file located in the `.github/agents/` directory:
Use `agent` to reference a custom agent file in `.github/agents/` (omit the `.agent.md` extension):

```yaml wrap
engine:
id: copilot
agent: technical-doc-writer
agent: technical-doc-writer # .github/agents/technical-doc-writer.agent.md
```

The `agent` field value should match the agent file name without the `.agent.md` extension. For example, `agent: technical-doc-writer` references `.github/agents/technical-doc-writer.agent.md`.

See [Copilot Agent Files](/gh-aw/reference/copilot-custom-agents/) for details on creating and configuring custom agents.
See [Copilot Agent Files](/gh-aw/reference/copilot-custom-agents/) for details.

### Engine Environment Variables

Expand All @@ -135,17 +124,6 @@ The `api-target` field specifies a custom API endpoint hostname for the agentic

For a complete setup and debugging walkthrough for GHE Cloud with data residency, see [Debugging GHE Cloud with Data Residency](/gh-aw/troubleshooting/debug-ghe/).

```yaml wrap
engine:
id: copilot
api-target: api.acme.ghe.com
network:
allowed:
- defaults
- acme.ghe.com
- api.acme.ghe.com
```

The value must be a hostname only — no protocol or path (e.g., `api.acme.ghe.com`, not `https://api.acme.ghe.com/v1`). The field works with any engine.

**GHEC example** — specify your tenant-specific Copilot endpoint:
Expand Down
Loading