AI Engines (aka Coding Agents)

GitHub Agentic Workflows use AI Engines (normally a coding agent) to interpret and execute natural language instructions. Each coding agent has unique capabilities and configuration options.

Available Coding Agents

Copilot CLI
Claude by Anthropic (Claude Code)
OpenAI Codex
Google Gemini CLI

Using Copilot CLI

GitHub Copilot CLI is the default AI engine (coding agent).

To use Copilot CLI with GitHub Agentic Workflows:

Copilot CLI is the default AI engine (coding agent). You can optionally request the use of the Copilot CLI in your workflow frontmatter:
```
engine: copilot
```
Configure the COPILOT_GITHUB_TOKEN secret. See Authentication: COPILOT_GITHUB_TOKEN for setup instructions.

Using Claude by Anthropic (Claude Code)

To use Claude by Anthropic (aka Claude Code):

Request the use of the Claude by Anthropic engine in your workflow frontmatter:
```
engine: claude
```
Configure the ANTHROPIC_API_KEY secret. See Authentication: ANTHROPIC_API_KEY for setup instructions.

Using OpenAI Codex

To use OpenAI Codex:

Request the use of the Codex engine in your workflow frontmatter:
```
engine: codex
```
Configure the OPENAI_API_KEY secret. See Authentication: OPENAI_API_KEY for setup instructions.

Using Google Gemini CLI

To use Google Gemini CLI:

Request the use of the Gemini engine in your workflow frontmatter:
```
engine: gemini
```
Configure the GEMINI_API_KEY secret. See Authentication: GEMINI_API_KEY for setup instructions.

Extended Coding Agent Configuration

Workflows can specify extended configuration for the coding agent:

engine:
  id: copilot
  version: latest                       # defaults to latest
  model: gpt-5                          # defaults to claude-sonnet-4
  command: /usr/local/bin/copilot       # custom executable path
  args: ["--add-dir", "/workspace"]     # custom CLI arguments
  agent: agent-id                       # custom agent file identifier

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:

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

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 for details on creating and configuring custom agents.

Engine Environment Variables

All engines support custom environment variables through the env field:

engine:
  id: copilot
  env:
    DEBUG_MODE: "true"
    AWS_REGION: us-west-2
    CUSTOM_API_ENDPOINT: https://api.example.com

Environment variables can also be defined at workflow, job, step, and other scopes. See Environment Variables for complete documentation on precedence and all 13 env scopes.

Engine Command-Line Arguments

All engines support custom command-line arguments through the args field, injected before the prompt:

engine:
  id: copilot
  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.

Custom Engine Command

Override the default engine executable using the command field. Useful for testing pre-release versions, custom builds, or non-standard installations. Installation steps are automatically skipped.

engine:
  id: copilot
  command: /usr/local/bin/copilot-dev  # absolute path
  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.

Frontmatter - Complete configuration reference
Tools - Available tools and MCP servers
Security Guide - Security considerations for AI engines
MCPs - Model Context Protocol setup and configuration