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

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 of the Copilot CLI in your workflow frontmatter:
```
engine: copilot
```
Create a fine-grained GitHub Personal Access Token (PAT)

You need a GitHub Personal Access Token (PAT) with the copilot-requests scope to authenticate Copilot CLI. Create a fine-grained PAT at https://github.com/settings/personal-access-tokens/new.
- Select your user account, not an organization.
- Choose “Public repositories” access.
- Enable “Copilot Requests” permissions.
You must have “Public repositories” selected; otherwise, the Copilot Requests permission option will not appear.
Add the PAT to your GitHub Actions repository secrets as COPILOT_GITHUB_TOKEN:
Terminal window
```
gh aw secrets set COPILOT_GITHUB_TOKEN --value "<your-github-pat>"
```

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 ANTHROPIC_API_KEY GitHub Actions secret.

Create an Anthropic API key and add it to your repository:
Terminal window
```
gh aw secrets set ANTHROPIC_API_KEY --value "<your-anthropic-api-key>"
```

Using OpenAI Codex

To use OpenAI Codex:

Request the use of the Codex engine in your workflow frontmatter:
```
engine: codex
```
Configure OPENAI_API_KEY GitHub Actions secret.

Create an OpenAI API key and add it to your repository:
Terminal window
```
gh aw secrets set OPENAI_API_KEY --value "<your-openai-api-key>"
```

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 Filess 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