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
  api-target: api.acme.ghe.com          # custom API endpoint hostname (GHEC/GHES)

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.

Enterprise API Endpoint (`api-target`)

The api-target field specifies a custom API endpoint hostname for the agentic engine. Use this when running workflows against GitHub Enterprise Cloud (GHEC), GitHub Enterprise Server (GHES), or any custom AI endpoint.

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:

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

GHES example — use the enterprise Copilot endpoint:

engine:
  id: copilot
  api-target: api.enterprise.githubcopilot.com
network:
  allowed:
    - defaults
    - github.company.com
    - api.enterprise.githubcopilot.com

The specified hostname must also be listed in network.allowed for the firewall to permit outbound requests.

Custom API Endpoints via Environment Variables

Two environment variables receive special treatment when set in engine.env: OPENAI_BASE_URL (for codex) and ANTHROPIC_BASE_URL (for claude). When either is present, the AWF sandbox proxy automatically routes API calls to the specified host instead of the default api.openai.com or api.anthropic.com. Credential isolation and firewall enforcement remain active.

This enables workflows to use internal LLM routers, Azure OpenAI deployments, or other OpenAI-compatible endpoints without bypassing AWF’s security model.

engine:
  id: codex
  model: gpt-4o
  env:
    OPENAI_BASE_URL: "https://llm-router.internal.example.com/v1"
    OPENAI_API_KEY: ${{ secrets.LLM_ROUTER_KEY }}

network:
  allowed:
    - github.com
    - llm-router.internal.example.com   # must be listed here for the firewall to permit outbound requests

For Claude workflows routed through a custom Anthropic-compatible endpoint:

engine:
  id: claude
  env:
    ANTHROPIC_BASE_URL: "https://anthropic-proxy.internal.example.com"
    ANTHROPIC_API_KEY: ${{ secrets.PROXY_API_KEY }}

network:
  allowed:
    - github.com
    - anthropic-proxy.internal.example.com

The custom hostname is extracted from the URL and passed to the AWF --openai-api-target or --anthropic-api-target flag automatically at compile time. No additional configuration is required.

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