How to Configure AI Engines (Copilot, Claude, Codex, Custom) in GitHub Agentic Workflows

Configure AI engines in GitHub Agentic Workflows by setting the engine field in your workflow's YAML front-matter, using either a simple scalar (engine: copilot) or an expanded map with engine-specific options like model, args, and agent.

GitHub Agentic Workflows (gh-aw) is an open-source framework that lets you orchestrate coding tasks using natural language prompts. When you configure AI engines in GitHub Agentic Workflows, you select which large language model or agent interprets these prompts—whether that is GitHub Copilot, Anthropic Claude, OpenAI Codex, or a custom binary.

Supported AI Engines in gh-aw

The gh-aw CLI supports four primary engine identifiers, each mapped to a specific coding agent:

• copilot — The default GitHub Copilot CLI agent, hosted by GitHub and optimized for general coding tasks.
• claude — Anthropic's Claude models, selected for complex reasoning and higher token limits.
• codex — OpenAI's Codex models, useful for legacy codebases or specific OpenAI-compatible integrations.
• custom — Any external agent binary or custom Copilot agent file located in .github/agents/.

According to the source code in pkg/workflow/engine_validation.go, the validation layer checks the engine field against this allowed set and rejects invalid values with a descriptive error message.

Configuring the Engine in Workflow Front-Matter

Workflow files in gh-aw are Markdown files with YAML front-matter. You declare the AI engine at the top of the file using either a simple scalar or an expanded configuration map.

Simple Scalar Form

For most use cases, specify the engine as a single string value:

---
engine: copilot
---

This format is documented in docs/src/content/docs/reference/engines.md at lines 24-26. When you use the scalar form, gh-aw applies default settings for the selected engine, including the latest stable model version and standard CLI arguments.

Expanded Map Form

For advanced configuration—such as pinning a specific model version, passing custom CLI arguments, or referencing a custom agent file—use the expanded map syntax:

---
engine:
  id: claude
  version: latest
  model: claude-sonnet-3.5
  args: ["--add-dir", "/workspace"]
  agent: my-custom-agent
---

As shown in the reference documentation at lines 84-91, the id field is required and must match one of the supported engine identifiers. The args array allows you to pass arbitrary flags to the underlying agent binary, while the agent field specifies a custom agent file located in .github/agents/.

Engine-Specific Configuration and Secrets

Each AI engine requires specific authentication tokens and environment variables. The gh-aw CLI reads these from your environment or GitHub Secrets at runtime.

Copilot CLI Configuration

To use the Copilot engine, you must authenticate with GitHub and possess a Personal Access Token (PAT) with the copilot-requests scope. Export this token as COPILOT_GITHUB_TOKEN:

export COPILOT_GITHUB_TOKEN=ghp_xxxxxxxxxxxx

The Copilot-specific documentation in docs/src/content/docs/reference/engines.md (lines 22-26) notes that this engine is the default and requires no additional configuration if the token is present in the environment.

Claude (Anthropic) Setup

For the Claude engine, provide your Anthropic API key via the ANTHROPIC_API_KEY environment variable:

export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx

As documented at lines 54-60, you can optionally specify the model version in the expanded engine map (e.g., model: claude-opus-4) to override the default claude-sonnet-3.5.

OpenAI Codex Setup

The Codex engine requires an OpenAI API key exported as OPENAI_API_KEY:

export OPENAI_API_KEY=sk-xxxxxxxxxxxx

According to the reference at lines 72-78, the Codex engine supports legacy OpenAI models. You may need to specify an older model identifier in the model field if your workflow targets specific legacy behavior.

Custom Agent Configuration

Custom engines allow you to integrate third-party agents or specialized Copilot agents. To configure a custom engine, place your agent definition file in .github/agents/ and reference it in the agent field:

---
engine:
  id: custom
  agent: technical-doc-writer
---

The technical-doc-writer file must exist at .github/agents/technical-doc-writer.copilot. As noted at lines 95-100, the id field can be custom or any string that maps to your external binary, provided the binary is available in the system PATH.

Validation and Error Handling

The gh-aw CLI validates engine configuration before executing workflows. The validation logic resides in pkg/workflow/engine_validation.go, which checks that the engine identifier matches one of the allowed values: copilot, claude, codex, or custom.

If you provide an invalid engine identifier, the CLI returns a structured error message:

invalid engine: <value>. Valid engines are: copilot, claude, codex, custom.
Example:
engine: copilot

This error generation occurs at lines 82-89 of pkg/workflow/engine_validation.go. Additionally, the JSON schema definition in pkg/workflow/schema_validation.go (line 162) enumerates the valid engine strings, ensuring that validation occurs both at the schema level and in the Go validation logic.

Complete Configuration Examples

Example 1: Basic Copilot Workflow

---
engine: copilot
---

# Refactor Python Functions

Please refactor the following Python code to use list comprehensions instead of for-loops.

Example 2: Claude with Specific Model and Arguments

---
engine:
  id: claude
  model: claude-opus-4
  args: ["--thinking", "enabled"]
---

# Complex Architecture Review

Analyze the microservice architecture described below and identify potential failure points.

Example 3: Custom Agent for Documentation

---
engine:
  id: custom
  agent: technical-doc-writer
---

# Generate API Documentation

Create comprehensive API documentation for the following endpoints.

Summary

• Engine selection in gh-aw is controlled by the engine field in workflow front-matter, supporting copilot, claude, codex, and custom.
• Simple configuration uses scalar values (engine: claude), while advanced configuration uses expanded maps with id, model, args, and agent fields.
• Authentication requires environment-specific API keys: COPILOT_GITHUB_TOKEN for Copilot, ANTHROPIC_API_KEY for Claude, and OPENAI_API_KEY for Codex.
• Custom agents reside in .github/agents/ and are referenced via the agent field in the engine configuration.
• Validation occurs in pkg/workflow/engine_validation.go, which enforces allowed engine identifiers and provides helpful error messages for invalid configurations.

Frequently Asked Questions

How do I switch between Copilot and Claude in different workflows?

You specify the engine individually in each workflow file's front-matter. One workflow can use engine: copilot while another uses engine: claude or the expanded form with id: claude. The gh-aw CLI reads the configuration per-file during compilation, allowing you to mix engines across your workflow suite.

What is the difference between the custom engine and the agent field?

The custom engine identifier tells gh-aw to use an external agent binary not natively integrated into the CLI. The agent field, used with either copilot or custom engines, points to a specific agent definition file located in .github/agents/. For Copilot, this loads a custom Copilot agent; for custom engines, it may specify configuration for your external binary.

Why does my workflow fail with "invalid engine" error?

This error originates from pkg/workflow/engine_validation.go when the engine field contains a value not in the allowed set: copilot, claude, codex, or custom. Check your front-matter for typos, ensure the value is lowercase, and verify you are using the expanded map syntax correctly if specifying additional fields like model or args.

Can I pass custom CLI arguments to the AI engine?

Yes. Use the expanded map form of the engine configuration and include the args array. For example, args: ["--add-dir", "/workspace"] passes those flags to the underlying agent binary when the workflow executes. This works for all supported engines including custom external agents.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}