AI Engines

GitHub Agentic Workflows support multiple AI engines (coding agents) to interpret and execute natural language instructions. Each engine has unique capabilities and configuration options.

Experimental Engines

Claude and Codex engines are available but marked as experimental. They are not documented here but can still be used by setting engine: claude or engine: codex in your workflow frontmatter. For production workflows, we recommend using the GitHub Copilot CLI engine.

GitHub Copilot CLI

GitHub Copilot is the default and recommended AI engine for most workflows. The GitHub Copilot CLI provides MCP server support and is designed for conversational AI workflows.

engine: copilot

Extended Configuration

engine:
  id: copilot
  version: latest                       # Optional: defaults to latest
  model: gpt-5                          # Optional: defaults to claude-sonnet-4
  args: ["--add-dir", "/workspace"]     # Optional: custom CLI arguments

Configuration Options

• model: AI model (gpt-5 or claude-sonnet-4)
• version: CLI version to install
• args: Custom command-line arguments (supported by all engines)

Environment Variables

• COPILOT_MODEL: Alternative way to set the model

Required Secrets

• COPILOT_GITHUB_TOKEN: GitHub Personal Access Token (PAT) with “Copilot Requests” permission
• GH_AW_GITHUB_TOKEN (optional): Required for GitHub Tools Remote Mode

Authenticating with a Personal Access Token (PAT)

To use the Copilot engine, you need a fine-grained Personal Access Token with the “Copilot Requests” permission enabled:

1. Visit https://github.com/settings/personal-access-tokens/new
2. Under “Resource owner”, select your user account (not an organization, see note below).
3. Under “Repository access,” select “Public repositories”
4. Under “Permissions,” click “Add permissions” and select “Copilot Requests”. If you are not finding this option, review steps 2 and 3.
5. Generate your token
6. Add the token to your repository secrets as COPILOT_GITHUB_TOKEN:

gh aw secrets set COPILOT_GITHUB_TOKEN --value "<your-github-pat>"

Legacy Tokens Removed

The COPILOT_CLI_TOKEN and GH_AW_COPILOT_TOKEN secret names are no longer supported as of v0.26+. If you’re using these tokens, please migrate to COPILOT_GITHUB_TOKEN.

The legacy secret name GH_AW_GITHUB_TOKEN is still supported for backward compatibility, but COPILOT_GITHUB_TOKEN is now the recommended name for Copilot operations.

For GitHub Tools Remote Mode, also configure:

gh aw secrets set GH_AW_GITHUB_TOKEN --value "<your-github-pat>"

For more information about GitHub Copilot CLI authentication, see the official documentation.

Note

The Copilot engine does not have built-in web-search support. You can add web search capabilities using third-party MCP servers. See the Using Web Search for available options and setup instructions.

Network Permissions

The Copilot engine supports network access control through the network: configuration at the workflow level. When network permissions are configured, you can enable AWF (Agent Workflow Firewall) to enforce domain-based access controls. AWF is sourced from github.com/githubnext/gh-aw-firewall.

Enable network permissions and firewall in your workflow:

engine: copilot

network:
  firewall: true           # Enable AWF enforcement
  allowed:
    - defaults             # Basic infrastructure domains
    - python              # Python ecosystem
    - "api.example.com"   # Custom domain

When enabled, AWF wraps the Copilot CLI execution and enforces the configured domain allowlist, logging all network activity for audit purposes. This provides network egress control and an additional layer of security for workflows that need strict network access control.

Advanced Firewall Configuration:

Additional AWF settings can be configured through the network configuration:

network:
  allowed:
    - defaults
    - python
  firewall:
    version: "v1.0.0"                    # Optional: AWF version (defaults to latest)
    log-level: debug                     # Optional: debug, info (default), warn, error
    args: ["--custom-arg", "value"]      # Optional: additional AWF arguments

Firewall Configuration Formats:

The firewall field supports multiple formats:

# Enable with defaults
network:
  firewall: true

# Enable with empty object (same as true)
network:
  firewall:

# Configure log level
network:
  firewall:
    log-level: info    # Options: debug, info (default), warn, error

# Disable firewall using boolean
network:
  firewall: false

# Disable firewall using string (equivalent to false)
network:
  firewall: "disable"

# Custom configuration with version and arguments
network:
  firewall:
    version: "v0.1.0"
    log-level: debug
    args: ["--verbose"]

Disabling the Firewall

Deprecated

The network.firewall: false configuration is deprecated. Use sandbox.agent: false instead.

To disable the firewall for any engine that supports it, use sandbox.agent: false:

engine: copilot
network:
  allowed:
    - defaults
    - python
    - "api.example.com"
sandbox:
  agent: false

Legacy approach (deprecated):

strict: false
network:
  allowed:
    - defaults
    - python
    - "api.example.com"
  firewall: false

When the firewall is disabled:

• Network permissions still apply for content sanitization
• The agent can make network requests without firewall enforcement
• This is useful during development or when the firewall is incompatible with your workflow

See the Network Permissions documentation for details on configuring allowed domains and ecosystem identifiers.

Custom Engine

Define custom GitHub Actions steps without AI interpretation for deterministic workflows.

engine: custom

Extended Configuration

engine:
  id: custom
  steps:
    - name: Install dependencies
      run: npm ci

Custom Agent Files

All AI engines support custom agent files that provide specialized instructions and behavior. See the Custom Agent Files reference for complete documentation on creating and using 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.

Engine Error Patterns

All engines support custom error pattern recognition for enhanced log validation:

engine:
  id: copilot
  error_patterns:
    - pattern: "\\[(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2})\\]\\s+(ERROR):\\s+(.+)"
      level_group: 2
      message_group: 3
      description: "Custom error format with timestamp"

Migration Between Engines

Switch engines by changing the engine field in your frontmatter:

# Simple switch
engine: copilot

# With configuration
engine:
  id: copilot
  model: gpt-5              # Optional; defaults to claude-sonnet-4
  version: latest

Engine-specific features may not be available when switching engines.

Related Documentation

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