From b4b03916eb7d3eab9ae650c651830d8688552f08 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Sep 2025 00:36:49 +0000 Subject: [PATCH 1/2] Initial plan From c983d0f8a745af9131d23f836d10d9372c15f3ab Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Sep 2025 00:47:19 +0000 Subject: [PATCH 2/2] Create comprehensive engine documentation with separate pages Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/reference/engines.md | 340 +++++++----- .../content/docs/reference/engines/claude.md | 317 +++++++++++ .../content/docs/reference/engines/codex.md | 415 ++++++++++++++ .../content/docs/reference/engines/custom.md | 522 ++++++++++++++++++ 4 files changed, 1449 insertions(+), 145 deletions(-) create mode 100644 docs/src/content/docs/reference/engines/claude.md create mode 100644 docs/src/content/docs/reference/engines/codex.md create mode 100644 docs/src/content/docs/reference/engines/custom.md diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md index 74c1a6217e0..06b16f8a4e0 100644 --- a/docs/src/content/docs/reference/engines.md +++ b/docs/src/content/docs/reference/engines.md @@ -1,103 +1,157 @@ --- title: AI Engines -description: Complete guide to AI engines available in GitHub Agentic Workflows, including Claude, Codex, and custom engines with their specific configuration options. +description: Overview of AI engines available in GitHub Agentic Workflows, including Claude, Codex, and custom engines with links to detailed configuration guides. sidebar: order: 1 --- -GitHub Agentic Workflows support multiple AI engines to interpret and execute natural language instructions. Each engine has unique capabilities and configuration options. +GitHub Agentic Workflows support multiple engines to interpret and execute natural language instructions or run custom GitHub Actions steps. Each engine has unique capabilities, configuration options, and use cases. -## Available Engines +## Quick Engine Reference + +| Engine | Type | Status | Best For | Documentation | +|--------|------|--------|----------|---------------| +| [Claude](/gh-aw/reference/engines/claude/) | AI | Stable ✅ | Reasoning, code analysis, general workflows | [View Guide →](/gh-aw/reference/engines/claude/) | +| [Codex](/gh-aw/reference/engines/codex/) | AI | Experimental ⚠️ | Code generation, specialized integrations | [View Guide →](/gh-aw/reference/engines/codex/) | +| [Custom](/gh-aw/reference/engines/custom/) | Traditional | Stable ✅ | Deterministic steps, hybrid workflows | [View Guide →](/gh-aw/reference/engines/custom/) | + +## Engine Types + +### AI Engines + +AI engines interpret natural language instructions and execute them using various tools and capabilities: + +- **Claude**: Uses Anthropic's Claude Code CLI with excellent reasoning capabilities +- **Codex**: Uses OpenAI Codex CLI with specialized code generation features + +### Traditional Engines -### Claude (Default) +Traditional engines execute predefined GitHub Actions steps without AI interpretation: -Claude Code is the default and recommended AI engine for most workflows. It excels at reasoning, code analysis, and understanding complex contexts. +- **Custom**: Executes user-defined GitHub Actions steps for deterministic workflows +## Quick Start Examples + +### Claude Engine (Recommended) ```yaml +--- engine: claude +--- + +# Analyze Code Quality + +Review the code in this repository and suggest improvements for performance and maintainability. ``` -**Extended configuration:** +### Codex Engine ```yaml +--- +engine: codex +--- + +# Generate API Tests + +Create comprehensive test cases for the REST API endpoints in this project. +``` + +### Custom Engine +```yaml +--- engine: - id: claude - version: beta - model: claude-3-5-sonnet-20241022 - max-turns: 5 - env: - AWS_REGION: us-west-2 - DEBUG_MODE: "true" + id: custom + steps: + - name: Run tests + run: npm test + - name: Deploy + uses: actions/deploy@v1 +--- + +# Traditional GitHub Actions Steps + +This workflow runs predefined steps without AI interpretation. ``` -**Features:** -- Excellent reasoning and code analysis capabilities -- Supports max-turns for cost control -- Uses MCP servers for tool integration -- Generates `mcp-servers.json` configuration +## Available Engines + +### [Claude Engine](/gh-aw/reference/engines/claude/) (Default) -### Codex (Experimental) +The recommended AI engine for most workflows with excellent reasoning and code analysis capabilities. -OpenAI Codex CLI with MCP server support. Designed for code-focused tasks and integration scenarios. +- **Type**: AI Engine +- **Status**: Stable ✅ +- **Network Isolation**: ✅ Python hooks with domain allow-lists +- **Version Control**: ✅ npm package versions +- **Max Turns**: ✅ Cost control support +**Quick Config:** ```yaml -engine: codex +engine: + id: claude + version: latest + max-turns: 5 ``` -**Extended configuration:** +[**→ View Complete Claude Documentation**](/gh-aw/reference/engines/claude/) + +### [Codex Engine](/gh-aw/reference/engines/codex/) (Experimental) + +AI engine optimized for code generation and specialized development tasks. + +- **Type**: AI Engine +- **Status**: Experimental ⚠️ +- **Network Isolation**: ⚠️ Limited to specific tools +- **Version Control**: ✅ npm package versions +- **Custom Config**: ✅ TOML configuration support + +**Quick Config:** ```yaml engine: id: codex model: gpt-4 - user-agent: custom-workflow-name - env: - OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY_CI }} config: | - [custom_section] - key1 = "value1" - key2 = "value2" - - [server_settings] - timeout = 60 - retries = 3 + [custom] + setting = "value" ``` -**Features:** -- Code-focused AI engine -- Generates `config.toml` for MCP server configuration -- Supports custom TOML configuration via `config` field -- Configurable user agent for GitHub MCP server -- Requires `OPENAI_API_KEY` secret - -**Codex-specific fields:** -- **`user-agent`** (optional): Custom user agent string for GitHub MCP server configuration -- **`config`** (optional): Additional TOML configuration text appended to generated config.toml +[**→ View Complete Codex Documentation**](/gh-aw/reference/engines/codex/) -### Custom Engine +### [Custom Engine](/gh-aw/reference/engines/custom/) -For advanced users who want to define completely custom GitHub Actions steps instead of using AI interpretation. +Execute traditional GitHub Actions steps without AI interpretation. -```yaml -engine: custom -``` +- **Type**: Traditional Engine +- **Status**: Stable ✅ +- **Network Isolation**: ❌ Manual implementation required +- **Version Control**: ✅ Action version pinning +- **Direct Control**: ✅ Exact step execution -**Extended configuration:** +**Quick Config:** ```yaml engine: id: custom steps: - - name: Custom step - run: echo "Custom logic here" - - uses: actions/setup-node@v4 - with: - node-version: '18' + - name: Build + run: make build + - uses: actions/deploy@v1 ``` -**Features:** -- Execute user-defined GitHub Actions steps -- No AI interpretation - direct step execution -- Useful for deterministic workflows or hybrid approaches +[**→ View Complete Custom Documentation**](/gh-aw/reference/engines/custom/)** -## Engine-Specific Configuration +## Feature Comparison + +| Feature | Claude | Codex | Custom | +|---------|--------|--------|--------| +| **AI Interpretation** | ✅ | ✅ | ❌ | +| **Network Isolation** | ✅ Full | ⚠️ Limited | ❌ Manual | +| **Version Control** | ✅ npm | ✅ npm | ✅ Actions | +| **Max Turns** | ✅ | ❌ | ⚠️ No effect | +| **Tools Whitelist** | ✅ | ✅ | ❌ | +| **HTTP Transport** | ✅ | ❌ | ❌ | +| **Custom Config** | ❌ | ✅ TOML | ❌ | +| **Environment Variables** | ✅ | ✅ | ✅ | +| **Experimental** | ❌ | ✅ | ❌ | + +## Common Configuration ### Environment Variables @@ -105,138 +159,134 @@ All engines support custom environment variables through the `env` field: ```yaml engine: - id: claude + id: claude # or codex, custom env: DEBUG_MODE: "true" AWS_REGION: us-west-2 CUSTOM_API_ENDPOINT: https://api.example.com ``` -**Common use cases:** -- Override default API keys (e.g., `OPENAI_API_KEY` for Codex) -- Set region-specific configuration -- Enable debug modes -- Configure custom endpoints - -### Error Patterns +### Version Control -Both Claude and Codex engines support custom error pattern recognition for enhanced log validation: +Engines support version specification for their underlying tools: ```yaml +# Claude: Controls @anthropic-ai/claude-code version engine: - id: codex - 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" -``` - -## Codex Engine Advanced Configuration - -The Codex engine supports additional customization through the `config` field, which allows you to append raw TOML configuration to the generated `config.toml` file. - -### Custom Configuration Example + id: claude + version: latest # or beta, v1.2.3 -```yaml +# Codex: Controls @openai/codex version engine: id: codex - config: | - # Custom logging configuration - [logging] - level = "debug" - file = "/tmp/codex-debug.log" - - # Server timeout settings - [server] - timeout = 120 - max_connections = 10 - - # Custom tool configurations - [tools.custom_analyzer] - enabled = true - mode = "strict" -``` + version: latest # or beta, v2.1.0 -### Generated Output - -This configuration generates a `config.toml` file with the structure: - -```toml -[history] -persistence = "none" - -[mcp_servers.github] -user_agent = "workflow-name" -command = "docker" -args = ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server:sha-09deac4"] -env = { "GITHUB_PERSONAL_ACCESS_TOKEN" = "${{ secrets.GITHUB_TOKEN }}" } - -# Custom configuration -[logging] -level = "debug" -file = "/tmp/codex-debug.log" - -[server] -timeout = 120 -max_connections = 10 - -[tools.custom_analyzer] -enabled = true -mode = "strict" +# Custom: Control action versions in steps +engine: + id: custom + steps: + - uses: actions/setup-node@v4 # Pin to v4 ``` -### Best Practices for Custom Config - -1. **Validate TOML**: Ensure your configuration is valid TOML syntax -2. **Avoid conflicts**: Don't override standard sections like `[history]` or `[mcp_servers.*]` -3. **Use descriptive sections**: Name your configuration sections clearly -4. **Document purpose**: Include comments in your TOML to explain custom settings -5. **Test thoroughly**: Validate that your custom configuration works as expected - ## Engine Selection Guidelines -**Choose Claude when:** +**Choose [Claude](/gh-aw/reference/engines/claude/) when:** - You need strong reasoning and analysis capabilities - Working with complex code review or documentation tasks - Performing multi-step reasoning workflows - You want the most stable and well-tested engine +- Network security is important -**Choose Codex when:** +**Choose [Codex](/gh-aw/reference/engines/codex/) when:** - You need code-specific AI capabilities - Working with specialized MCP server configurations - Requiring custom TOML configuration for advanced scenarios - You're comfortable with experimental features -**Choose Custom when:** +**Choose [Custom](/gh-aw/reference/engines/custom/) when:** - You need deterministic, traditional GitHub Actions behavior - Building hybrid workflows with some AI and some traditional steps - You have specific requirements that AI engines can't meet - Testing or prototyping workflow components +- Maximum control over execution is required ## Migration Between Engines -Switching between engines is straightforward - just change the `engine` field in your frontmatter: +Switching between engines requires updating the `engine` field and potentially adjusting configuration: + +### Claude ↔ Codex Migration ```yaml # From Claude to Codex -engine: claude # Old -engine: codex # New +engine: claude # Remove +engine: codex # Add +# Plus: change ANTHROPIC_API_KEY to OPENAI_API_KEY + +# From Codex to Claude +engine: codex # Remove +engine: claude # Add +# Plus: change OPENAI_API_KEY to ANTHROPIC_API_KEY +``` + +### AI → Custom Migration + +```yaml +# From AI engine +engine: claude +# Instruction: "Run tests and deploy" -# With configuration preservation +# To Custom engine engine: - id: codex # Changed from claude - model: gpt-4 # Add codex-specific options - config: | # Codex-only feature - [custom] - setting = "value" + id: custom + steps: + - name: Run tests + run: npm test + - name: Deploy + run: ./deploy.sh +``` + +### Custom → AI Migration + +```yaml +# From Custom engine +engine: + id: custom + steps: + - name: Complex deployment + run: ./complex-deploy.sh + +# To AI engine +engine: claude +# Instruction: "Deploy the application using the deployment script" ``` -Note that engine-specific features (like `config` for Codex or `max-turns` for Claude) may not be available when switching engines. +## Network Security + +### Claude Engine Network Isolation + +- **Implementation**: Python hooks with domain validation +- **Configuration**: `network.allowed` with domain patterns +- **Ecosystem Bundles**: Predefined domain sets (`bundle:node`, `bundle:python`, etc.) +- **Coverage**: System-wide network interception + +### Codex Engine Network Limitations + +- **Implementation**: Tool-specific restrictions +- **Configuration**: Per-tool domain settings +- **Coverage**: Limited to specific tools (e.g., Playwright) +- **Manual Setup**: Requires explicit tool configuration + +### Custom Engine Network Control + +- **Implementation**: Manual setup in steps +- **Configuration**: User-defined network restrictions +- **Coverage**: Depends on user implementation +- **Examples**: iptables, proxy configuration ## Related Documentation - [Frontmatter Options](/gh-aw/reference/frontmatter/) - Complete configuration reference -- [Tools Configuration](/gh-aw/reference/tools/) - Available tools and MCP servers +- [Tools Configuration](/gh-aw/reference/tools/) - Available tools and MCP servers +- [Network Configuration](/gh-aw/reference/network/) - Network isolation and domain management - [Security Guide](/gh-aw/guides/security/) - Security considerations for AI engines - [MCPs](/gh-aw/guides/mcps/) - Model Context Protocol setup and configuration \ No newline at end of file diff --git a/docs/src/content/docs/reference/engines/claude.md b/docs/src/content/docs/reference/engines/claude.md new file mode 100644 index 00000000000..d44b30e864c --- /dev/null +++ b/docs/src/content/docs/reference/engines/claude.md @@ -0,0 +1,317 @@ +--- +title: Claude Engine +description: Complete guide to the Claude engine, including configuration, network isolation, version control, and features. +sidebar: + order: 1 +--- + +The Claude engine is the default and recommended AI engine for GitHub Agentic Workflows. It uses Anthropic's Claude Code CLI to interpret and execute natural language instructions with excellent reasoning and code analysis capabilities. + +## Basic Configuration + +### Simple Configuration + +```yaml +engine: claude +``` + +### Extended Configuration + +```yaml +engine: + id: claude + version: beta # Optional: CLI version (default: latest) + model: claude-3-5-sonnet-20241022 # Optional: specific model + max-turns: 5 # Optional: max chat iterations per run + env: # Optional: environment variables + AWS_REGION: us-west-2 + DEBUG_MODE: "true" + CUSTOM_API_ENDPOINT: https://api.example.com +``` + +## Frontmatter Configuration + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `id` | string | `claude` | Engine identifier (required) | +| `version` | string | `latest` | Claude Code CLI version | +| `model` | string | `claude-3-5-sonnet-20241022` | Specific LLM model | +| `max-turns` | number | none | Maximum chat iterations per run | +| `env` | object | none | Custom environment variables | + +### Environment Variables + +The Claude engine supports custom environment variables that are passed to the execution environment: + +```yaml +engine: + id: claude + env: + # Override API key (uses secrets.ANTHROPIC_API_KEY by default) + ANTHROPIC_API_KEY: ${{ secrets.CUSTOM_ANTHROPIC_KEY }} + + # Debug and development settings + DEBUG_MODE: "true" + DISABLE_TELEMETRY: "1" + DISABLE_ERROR_REPORTING: "1" + + # Regional configuration + AWS_REGION: us-west-2 + + # Custom API endpoints + CUSTOM_API_ENDPOINT: https://api.example.com +``` + +**Note**: The following environment variables are automatically set and should not be overridden: +- `GITHUB_AW_PROMPT`: Path to the prompt file +- `GITHUB_AW_SAFE_OUTPUTS`: Safe outputs configuration +- `GITHUB_AW_MAX_TURNS`: Max turns setting +- `DISABLE_BUG_COMMAND`: Security setting + +## Version Control + +The Claude engine supports version control through the `version` field, which controls the version of the `@anthropic-ai/claude-code` npm package used. + +### Version Specification + +```yaml +engine: + id: claude + version: latest # Use latest version (default) + +engine: + id: claude + version: beta # Use beta version + +engine: + id: claude + version: v1.2.3 # Use specific version +``` + +### Generated GitHub Actions Step + +The version specification controls the npm package installation: + +```yaml +# With version: latest (default) +run: npx @anthropic-ai/claude-code@latest --debug --verbose ... + +# With version: beta +run: npx @anthropic-ai/claude-code@beta --debug --verbose ... + +# With version: v1.2.3 +run: npx @anthropic-ai/claude-code@v1.2.3 --debug --verbose ... +``` + +## Network Isolation + +The Claude engine implements network isolation through Python-based hooks that restrict network access to allowed domains only. + +### How Network Isolation Works + +1. **Domain Allow-lists**: Configure allowed domains in workflow frontmatter +2. **Python Hook Script**: Generated hook intercepts network requests +3. **Settings File**: Claude settings.json enforces network restrictions +4. **Ecosystem Bundles**: Predefined domain sets for common tools + +### Configuration + +```yaml +# In workflow frontmatter +network: + allowed: + - "api.github.com" + - "*.example.com" + - "trusted.org" +``` + +### Ecosystem Domain Bundles + +Use predefined domain bundles for common development ecosystems: + +```yaml +network: + allowed: + - "bundle:node" # npm, yarn, node.js domains + - "bundle:python" # pip, pypi, conda domains + - "bundle:github" # GitHub-related domains + - "bundle:containers" # Docker, container registries + - "api.custom.com" # Custom domain +``` + +Available bundles: +- `defaults`: SSL certificates, package managers +- `containers`: Docker Hub, GitHub Container Registry, Quay +- `dotnet`: NuGet, .NET domains +- `github`: GitHub CDN, raw content, LFS +- `go`: Go modules, proxy, sum database +- `java`: Maven, Gradle, Oracle JDK +- `node`: npm, yarn, Node.js, pnpm, bun, deno +- `python`: PyPI, conda, pip +- `ruby`: RubyGems, bundler +- `rust`: crates.io, rustup +- And more... + +### Generated Network Hook + +When network isolation is configured, the Claude engine generates: + +1. **Settings Generation Step**: Creates Claude settings.json +```yaml +- name: Generate Claude Settings + run: | + mkdir -p /tmp/.claude + cat > /tmp/.claude/settings.json << 'EOF' + { + "network": { + "allowedDomains": ["api.github.com", "*.example.com"] + } + } + EOF +``` + +2. **Network Hook Step**: Creates Python validation script +```yaml +- name: Setup Network Permissions Hook + run: | + cat > /tmp/network_hook.py << 'EOF' + #!/usr/bin/env python3 + # Network permissions validator for Claude Code engine + ALLOWED_DOMAINS = ["api.github.com", "*.example.com"] + # ... validation logic ... + EOF + chmod +x /tmp/network_hook.py +``` + +3. **Execution with Settings**: Claude Code is invoked with settings +```bash +npx @anthropic-ai/claude-code@latest --settings /tmp/.claude/settings.json ... +``` + +### Network Hook Implementation + +The network hook is a Python script that: + +- **Domain Extraction**: Parses URLs and search queries to extract domains +- **Wildcard Matching**: Supports patterns like `*.example.com` +- **Validation Logic**: Allows/blocks requests based on domain allow-list +- **Logging**: Records network access attempts for debugging + +## Features + +### Core Capabilities + +- **Excellent Reasoning**: Strong analytical and problem-solving capabilities +- **Code Analysis**: Deep understanding of code structure and patterns +- **MCP Tool Support**: Full Model Context Protocol integration +- **Tool Allow-listing**: Precise control over available tools + +### Supported Features + +| Feature | Supported | Description | +|---------|-----------|-------------| +| Max Turns | ✅ | Cost control through turn limiting | +| Tools Whitelist | ✅ | MCP tool allow-listing | +| HTTP Transport | ✅ | Both stdio and HTTP MCP transport | +| Network Isolation | ✅ | Domain-based access control | +| Custom Environment | ✅ | Environment variable customization | +| Version Control | ✅ | CLI version specification | + +### MCP Server Integration + +The Claude engine generates `mcp-servers.json` configuration for tool integration: + +```json +{ + "mcpServers": { + "github": { + "command": "docker", + "args": ["run", "-i", "--rm", "--network=host", "..."], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "..." + } + }, + "safe-outputs": { + "command": "npx", + "args": ["@github/safe-outputs-mcp-server@latest"], + "transport": "stdio" + } + } +} +``` + +## Security Considerations + +### Default Security Settings + +The Claude engine automatically sets secure defaults: + +```yaml +env: + DISABLE_TELEMETRY: "1" # Disable usage telemetry + DISABLE_ERROR_REPORTING: "1" # Disable error reporting + DISABLE_BUG_COMMAND: "1" # Disable bug reporting command +``` + +### API Key Management + +- Uses `secrets.ANTHROPIC_API_KEY` by default +- Can be overridden with custom secret via `env` configuration +- Never logged or exposed in workflow outputs + +### Network Security + +- Network isolation prevents unauthorized external requests +- Domain allow-lists provide fine-grained access control +- Ecosystem bundles reduce configuration while maintaining security + +## Troubleshooting + +### Common Issues + +**Network Access Denied** +``` +Error: Network request to unauthorized domain blocked +``` +Solution: Add required domains to network allow-list or use appropriate ecosystem bundle. + +**Version Not Found** +``` +Error: Package @anthropic-ai/claude-code@v999 not found +``` +Solution: Verify the version exists in npm registry or use `latest` or `beta`. + +**API Key Missing** +``` +Error: ANTHROPIC_API_KEY environment variable not set +``` +Solution: Ensure `secrets.ANTHROPIC_API_KEY` is configured in repository secrets. + +### Debug Configuration + +Enable verbose logging for troubleshooting: + +```yaml +engine: + id: claude + env: + DEBUG_MODE: "true" +``` + +The Claude engine automatically includes: +- `--debug` flag for detailed execution logging +- `--verbose` flag for enhanced output +- `--output-format json` for structured responses + +## Related Documentation + +- [Network Configuration](/gh-aw/reference/network/) - Network isolation and domain management +- [Tools Configuration](/gh-aw/reference/tools/) - MCP servers and tool configuration +- [Safe Outputs](/gh-aw/reference/safe-outputs/) - Output validation and security +- [Frontmatter Reference](/gh-aw/reference/frontmatter/) - Complete configuration options + +## External Links + +- [Anthropic Claude Code CLI](https://github.com/anthropics/claude-code) - Official Claude Code repository +- [Model Context Protocol](https://spec.modelcontextprotocol.io/) - MCP specification +- [Anthropic API Documentation](https://docs.anthropic.com/) - Claude API reference \ No newline at end of file diff --git a/docs/src/content/docs/reference/engines/codex.md b/docs/src/content/docs/reference/engines/codex.md new file mode 100644 index 00000000000..ed59bc64409 --- /dev/null +++ b/docs/src/content/docs/reference/engines/codex.md @@ -0,0 +1,415 @@ +--- +title: Codex Engine +description: Complete guide to the Codex engine, including configuration, network isolation, version control, and features. +sidebar: + order: 2 +--- + +The Codex engine is an experimental AI engine for GitHub Agentic Workflows that uses OpenAI Codex CLI with MCP server support. It's designed for code-focused tasks and advanced integration scenarios. + +:::caution[Experimental Feature] +The Codex engine is experimental and may have breaking changes. Use with caution in production workflows. +::: + +## Basic Configuration + +### Simple Configuration + +```yaml +engine: codex +``` + +### Extended Configuration + +```yaml +engine: + id: codex + version: latest # Optional: CLI version (default: latest) + model: gpt-4 # Optional: specific model + user-agent: custom-workflow-name # Optional: GitHub MCP user agent + env: # Optional: environment variables + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY_CI }} + DEBUG_MODE: "true" + config: | # Optional: custom TOML configuration + [custom_section] + key1 = "value1" + key2 = "value2" + + [server_settings] + timeout = 60 + retries = 3 +``` + +## Frontmatter Configuration + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `id` | string | `codex` | Engine identifier (required) | +| `version` | string | `latest` | Codex CLI version | +| `model` | string | Default model | Specific LLM model to use | +| `user-agent` | string | Workflow name | GitHub MCP server user agent | +| `env` | object | none | Custom environment variables | +| `config` | string | none | Additional TOML configuration | + +### Environment Variables + +The Codex engine supports custom environment variables: + +```yaml +engine: + id: codex + env: + # OpenAI API configuration (required) + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + + # Debug and development settings + DEBUG_MODE: "true" + CODEX_LOG_LEVEL: "debug" + + # Custom API endpoints + OPENAI_BASE_URL: https://api.openai.com/v1 + + # GitHub integration + GITHUB_PERSONAL_ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +**Note**: The following environment variables are automatically set: +- `GITHUB_AW_PROMPT`: Path to the prompt file +- `GITHUB_STEP_SUMMARY`: GitHub Actions step summary +- `OPENAI_API_KEY`: Required OpenAI API key + +### Custom TOML Configuration + +The Codex engine supports additional TOML configuration through the `config` field: + +```yaml +engine: + id: codex + config: | + # Custom logging configuration + [logging] + level = "debug" + file = "/tmp/codex-debug.log" + + # Server timeout settings + [server] + timeout = 120 + max_connections = 10 + + # Custom tool configurations + [tools.custom_analyzer] + enabled = true + mode = "strict" + + # MCP server overrides + [mcp_servers.custom] + command = "custom-mcp-server" + args = ["--mode", "production"] +``` + +## Version Control + +The Codex engine supports version control through the `version` field, which controls the version of the `@openai/codex` npm package. + +### Version Specification + +```yaml +engine: + id: codex + version: latest # Use latest version (default) + +engine: + id: codex + version: beta # Use beta version + +engine: + id: codex + version: v2.1.0 # Use specific version +``` + +### Generated Installation Steps + +The version specification controls the npm installation: + +```yaml +# With version: latest (default) +- name: Install Codex + run: npm install -g @openai/codex + +# With version: v2.1.0 +- name: Install Codex + run: npm install -g @openai/codex@v2.1.0 +``` + +### Node.js Setup + +The Codex engine automatically sets up Node.js 24: + +```yaml +- name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '24' +``` + +## Network Isolation + +The Codex engine implements network isolation through domain restrictions for Playwright and other tools, but does not use the same Python hook system as Claude. + +### How Network Isolation Works + +1. **Tool-level Restrictions**: Network access is controlled at the tool level +2. **Playwright Domains**: Allowed domains for browser automation +3. **MCP Configuration**: Network settings in config.toml +4. **No Global Hooks**: Unlike Claude, no global network interception + +### Configuration + +Network isolation is configured through tool-specific settings: + +```yaml +# In workflow frontmatter +tools: + playwright: + allowed_domains: + - "example.com" + - "*.trusted.com" + - "api.github.com" + +# Or using ecosystem bundles +tools: + playwright: + allowed_domains: + - "bundle:node" + - "bundle:github" + - "custom.domain.com" +``` + +### Playwright Network Isolation + +For Playwright tools, the Codex engine generates MCP configuration: + +```toml +[mcp_servers.playwright] +command = "npx" +args = [ + "@playwright/mcp@latest", + "--allowed-origins", + "example.com,*.trusted.com,api.github.com" +] +``` + +### Limited Network Isolation + +The Codex engine has more limited network isolation compared to Claude: + +- **Tool-specific**: Only certain tools support network restrictions +- **No Global Hooks**: No system-wide network interception +- **Manual Configuration**: Requires explicit tool configuration + +## Features + +### Core Capabilities + +- **Code-focused AI**: Optimized for code generation and analysis +- **MCP Integration**: Full Model Context Protocol support +- **Custom Configuration**: Flexible TOML configuration system +- **Tool Integration**: Specialized MCP server configurations + +### Supported Features + +| Feature | Supported | Description | +|---------|-----------|-------------| +| Max Turns | ❌ | Not supported in Codex engine | +| Tools Whitelist | ✅ | MCP tool allow-listing | +| HTTP Transport | ❌ | Only stdio transport supported | +| Network Isolation | ⚠️ | Limited to specific tools | +| Custom Environment | ✅ | Environment variable customization | +| Version Control | ✅ | CLI version specification | +| Custom TOML Config | ✅ | Unique to Codex engine | + +### MCP Server Integration + +The Codex engine generates `config.toml` for MCP server configuration: + +```toml +[history] +persistence = "none" + +[mcp_servers.github] +user_agent = "workflow-name" +command = "docker" +args = ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server:sha-09deac4"] +env = { "GITHUB_PERSONAL_ACCESS_TOKEN" = "${{ secrets.GITHUB_TOKEN }}" } + +[mcp_servers.safe_outputs] +command = "npx" +args = ["@github/safe-outputs-mcp-server@latest"] + +# Custom configuration appended here +[custom_section] +key1 = "value1" +key2 = "value2" +``` + +### User Agent Configuration + +The Codex engine supports custom user agent strings for GitHub MCP server: + +```yaml +engine: + id: codex + user-agent: my-custom-workflow +``` + +This sets the `user_agent` field in the GitHub MCP server configuration. + +## Execution Process + +### Installation Phase + +1. **Node.js Setup**: Install Node.js 24 +2. **Codex Installation**: Install `@openai/codex` package with specified version +3. **Authentication**: Login to Codex with OpenAI API key + +### Execution Phase + +1. **Config Generation**: Create `config.toml` with MCP servers and custom configuration +2. **Codex Execution**: Run Codex CLI with generated configuration +3. **Log Capture**: Capture output for debugging and analysis + +### Generated Execution Steps + +```yaml +- name: Execute Codex + run: | + # Setup logging + mkdir -p /tmp/aw-logs + + # Check Codex installation + which codex + codex --version + + # Authenticate with OpenAI + codex login --api-key "$OPENAI_API_KEY" + + # Execute with instruction + codex --full-auto exec "$INSTRUCTION" 2>&1 | tee /tmp/aw-logs/log.txt + env: + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + GITHUB_STEP_SUMMARY: ${{ env.GITHUB_STEP_SUMMARY }} +``` + +## Security Considerations + +### API Key Management + +- Requires `secrets.OPENAI_API_KEY` for authentication +- Can be overridden with custom secret via `env` configuration +- Uses GitHub secrets for secure credential management + +### Limited Network Security + +The Codex engine has weaker network isolation compared to Claude: + +- No global network hooks +- Tool-specific restrictions only +- Manual configuration required + +### Configuration Security + +- Custom TOML configuration is appended to generated config +- Validate TOML syntax to prevent injection +- Avoid overriding security-critical sections + +## Troubleshooting + +### Common Issues + +**API Key Missing** +``` +Error: OPENAI_API_KEY environment variable not set +``` +Solution: Configure `secrets.OPENAI_API_KEY` in repository secrets. + +**Version Not Found** +``` +Error: Package @openai/codex@v999 not found +``` +Solution: Verify version exists in npm registry or use `latest`. + +**Invalid TOML Configuration** +``` +Error: Failed to parse TOML configuration +``` +Solution: Validate TOML syntax in the `config` field. + +**Network Access Issues** +``` +Error: Network request blocked +``` +Solution: Configure allowed domains for specific tools like Playwright. + +### Debug Configuration + +Enable verbose logging: + +```yaml +engine: + id: codex + env: + DEBUG_MODE: "true" + CODEX_LOG_LEVEL: "debug" + config: | + [logging] + level = "debug" + file = "/tmp/codex-debug.log" +``` + +### TOML Configuration Best Practices + +1. **Validate Syntax**: Use a TOML validator before deployment +2. **Avoid Conflicts**: Don't override `[history]` or `[mcp_servers.*]` sections +3. **Use Comments**: Document custom configuration sections +4. **Test Thoroughly**: Validate configuration in development environment + +## Migration from Claude + +When migrating from Claude to Codex: + +1. **Remove Max Turns**: Codex doesn't support `max-turns` +2. **Update API Key**: Change from `ANTHROPIC_API_KEY` to `OPENAI_API_KEY` +3. **Configure Network**: Set tool-specific network restrictions +4. **Add Custom Config**: Use `config` field for advanced settings + +```yaml +# Claude configuration +engine: + id: claude + max-turns: 5 + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + +# Equivalent Codex configuration +engine: + id: codex + env: + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + config: | + [execution] + mode = "controlled" # Custom setting to limit iterations +``` + +## Related Documentation + +- [Custom TOML Configuration](/gh-aw/reference/frontmatter/#codex-engine-custom-configuration) - Detailed TOML configuration guide +- [Tools Configuration](/gh-aw/reference/tools/) - MCP servers and tool setup +- [Network Configuration](/gh-aw/reference/network/) - Network isolation principles +- [Engine Migration](/gh-aw/reference/engines/#migration-between-engines) - Switching between engines + +## External Links + +- [OpenAI Codex Documentation](https://platform.openai.com/docs/guides/code) - Official Codex documentation +- [OpenAI API Reference](https://platform.openai.com/docs/api-reference) - API documentation +- [Model Context Protocol](https://spec.modelcontextprotocol.io/) - MCP specification +- [TOML Specification](https://toml.io/en/) - TOML format documentation \ No newline at end of file diff --git a/docs/src/content/docs/reference/engines/custom.md b/docs/src/content/docs/reference/engines/custom.md new file mode 100644 index 00000000000..e33fbb66ae2 --- /dev/null +++ b/docs/src/content/docs/reference/engines/custom.md @@ -0,0 +1,522 @@ +--- +title: Custom Engine +description: Complete guide to the Custom engine for executing user-defined GitHub Actions steps without AI interpretation. +sidebar: + order: 3 +--- + +The Custom engine allows you to define traditional GitHub Actions steps that execute without AI interpretation. This is useful for deterministic workflows, hybrid AI/traditional approaches, or when you need precise control over workflow execution. + +## Basic Configuration + +### Simple Configuration + +```yaml +engine: custom +``` + +### Extended Configuration + +```yaml +engine: + id: custom + max-turns: 3 # Optional: for consistency (no effect) + env: # Optional: environment variables + NODE_ENV: production + DEBUG: "true" + steps: # Required: GitHub Actions steps + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + - name: Install dependencies + run: npm install + - name: Run tests + run: npm test + env: + CI: true +``` + +## Frontmatter Configuration + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `id` | string | `custom` | Engine identifier (required) | +| `max-turns` | number | none | Kept for consistency (no effect) | +| `env` | object | none | Environment variables for all steps | +| `steps` | array | none | GitHub Actions steps to execute | + +### Steps Configuration + +The `steps` field contains an array of standard GitHub Actions step definitions: + +```yaml +engine: + id: custom + steps: + # Action-based step + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + # Command-based step + - name: Run custom script + run: | + echo "Starting custom workflow" + ./scripts/custom-logic.sh + working-directory: ./src + + # Step with conditional execution + - name: Deploy to staging + if: github.ref == 'refs/heads/develop' + run: ./deploy.sh staging + env: + DEPLOY_KEY: ${{ secrets.STAGING_DEPLOY_KEY }} + + # Multi-line command step + - name: Complex build process + run: | + set -e + echo "Building application..." + make clean + make build + make test + echo "Build completed successfully" +``` + +### Environment Variables + +Environment variables can be set at the engine level and will be merged with step-specific environment variables: + +```yaml +engine: + id: custom + env: + # Global environment variables for all steps + NODE_ENV: production + API_BASE_URL: https://api.example.com + DEBUG_MODE: "true" + steps: + - name: Run application + run: node app.js + env: + # Step-specific environment variables + PORT: 3000 + # Inherits NODE_ENV, API_BASE_URL, DEBUG_MODE from engine level +``` + +## Version Control + +The Custom engine does not have version control in the traditional sense since it executes user-defined GitHub Actions steps directly. However, you can control versions of the actions you use: + +### Action Version Specification + +```yaml +engine: + id: custom + steps: + # Pin to specific major version + - name: Setup Node.js + uses: actions/setup-node@v4 + + # Pin to specific minor version + - name: Cache dependencies + uses: actions/cache@v3.3 + + # Pin to specific commit SHA (most secure) + - name: Deploy to AWS + uses: aws-actions/configure-aws-credentials@1e326a4557363cd93a3e77a6c0e2c6daf9c6b537 +``` + +### Best Practices for Versions + +1. **Pin Major Versions**: Use `@v4` instead of `@latest` +2. **Security Critical**: Use SHA pins for security-sensitive actions +3. **Regular Updates**: Keep action versions up to date +4. **Documentation**: Document why specific versions are chosen + +## Network Isolation + +The Custom engine does not implement network isolation like the AI engines. Network access depends on the GitHub Actions runner environment and the steps you define. + +### How Network Access Works + +1. **Runner Environment**: Network access is controlled by GitHub Actions runner +2. **Step-level Control**: Individual steps can implement their own network restrictions +3. **No Global Hooks**: No system-wide network interception +4. **Manual Implementation**: Network restrictions must be implemented in your steps + +### Implementing Network Restrictions + +You can implement network restrictions in your custom steps: + +```yaml +engine: + id: custom + steps: + # Setup network restrictions using iptables (Linux runners) + - name: Configure network restrictions + run: | + # Block all outbound except specific domains + sudo iptables -A OUTPUT -d api.github.com -j ACCEPT + sudo iptables -A OUTPUT -d *.example.com -j ACCEPT + sudo iptables -A OUTPUT -j DROP + + # Run your restricted application + - name: Run application with network restrictions + run: ./my-application +``` + +### Proxy Configuration + +For more sophisticated network control, you can use proxy servers: + +```yaml +engine: + id: custom + steps: + - name: Setup proxy + run: | + # Configure HTTP proxy for network filtering + export HTTP_PROXY=http://filtering-proxy:8080 + export HTTPS_PROXY=http://filtering-proxy:8080 + export NO_PROXY=localhost,127.0.0.1 + + - name: Run with proxy + run: curl https://api.example.com/data + env: + HTTP_PROXY: http://filtering-proxy:8080 + HTTPS_PROXY: http://filtering-proxy:8080 +``` + +## Features + +### Core Capabilities + +- **Direct Execution**: No AI interpretation, runs exactly as written +- **Standard Actions**: Full compatibility with GitHub Actions ecosystem +- **Conditional Logic**: Support for `if` conditions and expressions +- **Environment Control**: Flexible environment variable management + +### Supported Features + +| Feature | Supported | Description | +|---------|-----------|-------------| +| Max Turns | ⚠️ | Accepted but has no effect | +| Tools Whitelist | ❌ | Not applicable to custom steps | +| HTTP Transport | ❌ | Not applicable to custom steps | +| Network Isolation | ❌ | Must be implemented manually | +| Custom Environment | ✅ | Full environment variable support | +| Version Control | ✅ | Through action version pinning | +| Conditional Execution | ✅ | Full GitHub Actions `if` support | +| Matrix Builds | ✅ | Can be used in matrix strategies | + +### GitHub Actions Integration + +The Custom engine generates standard GitHub Actions steps: + +```yaml +# Generated workflow step +- name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + +- name: Install dependencies + run: npm install + env: + NODE_ENV: production + DEBUG_MODE: "true" + GITHUB_AW_PROMPT: /tmp/aw-prompts/prompt.txt + +- name: Ensure log file exists + run: | + echo "Custom steps execution completed" >> /tmp/aw-logs/log.txt + touch /tmp/aw-logs/log.txt +``` + +### Automatic Environment Variables + +The Custom engine automatically adds: + +- `GITHUB_AW_PROMPT`: Path to the prompt file (`/tmp/aw-prompts/prompt.txt`) +- User-defined environment variables from the `env` section +- Step-specific environment variables + +## Execution Process + +### No Installation Phase + +The Custom engine has no installation requirements since it uses standard GitHub Actions steps. + +### Execution Phase + +1. **Step Conversion**: Convert step definitions to YAML +2. **Environment Merging**: Merge engine-level and step-level environment variables +3. **Direct Execution**: Execute steps as standard GitHub Actions +4. **Log Generation**: Create log file for consistency + +### Generated Steps + +For each custom step, the engine: + +1. **Preserves Structure**: Maintains exact step definition +2. **Merges Environment**: Combines engine and step environment variables +3. **Adds Prompt**: Automatically includes `GITHUB_AW_PROMPT` environment variable + +## Use Cases + +### Hybrid Workflows + +Combine AI engines with custom steps: + +```yaml +# File: .github/workflows/hybrid-workflow.md +--- +on: push +engine: claude # AI engine for main logic +--- + +# AI Prompt +Analyze the code changes and generate a summary. + + + +``` + +```yaml +# File: .github/workflows/custom-deploy.md +--- +engine: custom # Custom steps for deployment +--- + +```yaml +engine: + id: custom + steps: + - name: Deploy to production + run: ./deploy.sh + if: github.ref == 'refs/heads/main' +``` + +### Testing and Development + +Use custom engine for testing workflow components: + +```yaml +engine: + id: custom + steps: + - name: Test step execution + run: echo "Testing workflow step" + + - name: Validate environment + run: | + echo "Node version: $(node --version)" + echo "NPM version: $(npm --version)" + echo "Current directory: $(pwd)" + echo "Environment: $NODE_ENV" +``` + +### Legacy Workflow Migration + +Migrate existing GitHub Actions workflows: + +```yaml +# Original .github/workflows/ci.yml +# jobs: +# test: +# steps: +# - uses: actions/checkout@v4 +# - uses: actions/setup-node@v4 +# - run: npm test + +# Migrated to gh-aw custom engine +engine: + id: custom + steps: + - name: Checkout code + uses: actions/checkout@v4 + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + - name: Run tests + run: npm test +``` + +## Security Considerations + +### No Built-in Isolation + +The Custom engine provides no built-in security isolation: + +- **Network Access**: Full network access by default +- **File System**: Full file system access +- **Secrets**: Access to all repository secrets +- **Permissions**: Inherits workflow permissions + +### Manual Security Implementation + +Implement security measures in your steps: + +```yaml +engine: + id: custom + steps: + # Validate inputs + - name: Validate inputs + run: | + if [[ ! "$INPUT_VALUE" =~ ^[a-zA-Z0-9_-]+$ ]]; then + echo "Invalid input format" + exit 1 + fi + + # Run with restricted permissions + - name: Run with limited user + run: | + # Create limited user + sudo useradd -m -s /bin/bash limited_user + # Run command as limited user + sudo -u limited_user ./safe-command.sh + + # Clean up sensitive data + - name: Cleanup + if: always() + run: | + rm -f /tmp/sensitive-data.txt + unset SECRET_VALUE +``` + +### Secret Management + +Handle secrets carefully in custom steps: + +```yaml +engine: + id: custom + steps: + - name: Use secrets securely + run: | + # Don't echo secrets + # echo "$SECRET_KEY" # DON'T DO THIS + + # Use secrets in variables without logging + export API_KEY="$SECRET_KEY" + ./app --api-key-from-env + env: + SECRET_KEY: ${{ secrets.API_SECRET }} +``` + +## Troubleshooting + +### Common Issues + +**Step YAML Syntax Error** +``` +Error: Invalid step definition in custom engine +``` +Solution: Validate YAML syntax in step definitions. + +**Environment Variable Not Available** +``` +Error: Required environment variable not set +``` +Solution: Check that variables are defined in engine `env` or step `env`. + +**Action Version Not Found** +``` +Error: Unable to resolve action +``` +Solution: Verify action exists and version is correct. + +**Permission Denied** +``` +Error: Permission denied running step +``` +Solution: Check file permissions or use `sudo` if needed. + +### Debugging Custom Steps + +Add debugging information to steps: + +```yaml +engine: + id: custom + env: + DEBUG: "true" + steps: + - name: Debug environment + run: | + echo "=== Environment Debug ===" + echo "Current user: $(whoami)" + echo "Current directory: $(pwd)" + echo "Environment variables:" + env | sort + echo "=== End Debug ===" + + - name: Your actual step + run: ./your-command +``` + +### Step Validation + +Validate step definitions before deployment: + +```bash +# Use GitHub Actions CLI to validate +gh workflow view .github/workflows/your-workflow.yml + +# Or use act to test locally +act -n # Dry run to check syntax +``` + +## Migration to Custom Engine + +### From AI Engines + +When migrating from AI engines to custom steps: + +1. **Define Explicit Steps**: Convert AI instructions to specific actions +2. **Handle Environment**: Move environment setup to custom steps +3. **Implement Security**: Add manual security measures +4. **Remove AI Features**: Remove AI-specific configuration + +```yaml +# AI engine (Claude) +engine: claude +tools: + - bash + - github + +# Equivalent custom engine +engine: + id: custom + steps: + - name: Setup environment + run: | + # Setup equivalent to AI tools + apt-get update && apt-get install -y curl jq + + - name: Execute logic + run: | + # Explicit commands instead of AI interpretation + ./specific-script.sh + curl -H "Authorization: token $GITHUB_TOKEN" \ + https://api.github.com/repos/owner/repo/issues +``` + +## Related Documentation + +- [GitHub Actions Documentation](https://docs.github.com/en/actions) - Complete GitHub Actions reference +- [Workflow Syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) - GitHub Actions YAML syntax +- [Include Directives](/gh-aw/reference/include-directives/) - Combining multiple workflow files +- [Hybrid Workflows](/gh-aw/guides/hybrid-workflows/) - Combining AI and custom engines + +## External Links + +- [GitHub Actions Marketplace](https://github.com/marketplace?type=actions) - Browse available actions +- [GitHub Actions Toolkit](https://github.com/actions/toolkit) - Build custom actions +- [act](https://github.com/nektos/act) - Run GitHub Actions locally +- [Super-Linter](https://github.com/github/super-linter) - Validate workflow files \ No newline at end of file