AI Engines (aka Coding Agents)

GitHub Agentic Workflows use AI Engines (normally a coding agent) to interpret and execute natural language instructions.

Available Coding Agents

Set engine: in your workflow frontmatter and configure the corresponding secret:

Engine	`engine:` value	Required Secret
GitHub Copilot CLI (default)	`copilot`	COPILOT_GITHUB_TOKEN
Claude by Anthropic (Claude Code)	`claude`	ANTHROPIC_API_KEY
OpenAI Codex	`codex`	OPENAI_API_KEY
Google Gemini CLI	`gemini`	GEMINI_API_KEY

Copilot CLI is the default — engine: can be omitted when using Copilot. See the linked authentication docs for secret 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

Pinning a Specific Engine Version

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

# 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.

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. 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"]

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