diff --git a/docs/configuration.md b/docs/configuration.md index 92a856b..ecc75bc 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -343,3 +343,31 @@ Many individual input parameters have been consolidated into `claude_args` or `s | `mcp_config` | Use `claude_args: "--mcp-config '{...}'"` | | `direct_prompt` | Use `prompt` input instead | | `override_prompt` | Use `prompt` with GitHub context variables | + +## Custom Executables for Specialized Environments + +For specialized environments like Nix, custom container setups, or other package management systems where the default installation doesn't work, you can provide your own executables: + +### Custom Claude Code Executable + +Use `path_to_claude_code_executable` to provide your own Claude Code binary instead of using the automatically installed version: + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + path_to_claude_code_executable: "/path/to/custom/claude" + # ... other inputs +``` + +### Custom Bun Executable + +Use `path_to_bun_executable` to provide your own Bun runtime instead of the default installation: + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + path_to_bun_executable: "/path/to/custom/bun" + # ... other inputs +``` + +**Important**: Using incompatible versions may cause the action to fail. Ensure your custom executables are compatible with the action's requirements. diff --git a/docs/faq.md b/docs/faq.md index 269728e..1836354 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -213,6 +213,44 @@ Check the GitHub Action log for Claude's run for the full execution trace. The trigger uses word boundaries, so `@claude` must be a complete word. Variations like `@claude-bot`, `@claude!`, or `claude@mention` won't work unless you customize the `trigger_phrase`. +### How can I use custom executables in specialized environments? + +For specialized environments like Nix, NixOS, or custom container setups where you need to provide your own executables: + +**Using a custom Claude Code executable:** + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + path_to_claude_code_executable: "/path/to/custom/claude" + # ... other inputs +``` + +**Using a custom Bun executable:** + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + path_to_bun_executable: "/path/to/custom/bun" + # ... other inputs +``` + +**Common use cases:** + +- Nix/NixOS environments where packages are managed differently +- Docker containers with pre-installed executables +- Custom build environments with specific version requirements +- Debugging specific issues with particular versions + +**Important notes:** + +- Using an older Claude Code version may cause problems if the action uses newer features +- Using an incompatible Bun version may cause runtime errors +- The action will skip automatic installation when custom paths are provided +- Ensure the custom executables are available in your GitHub Actions environment + ## Best Practices 1. **Always specify permissions explicitly** in your workflow file diff --git a/docs/usage.md b/docs/usage.md index 9ceadd7..5fda8d4 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -47,31 +47,33 @@ jobs: ## Inputs -| Input | Description | Required | Default | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------- | -| `anthropic_api_key` | Anthropic API key (required for direct API, not needed for Bedrock/Vertex) | No\* | - | -| `claude_code_oauth_token` | Claude Code OAuth token (alternative to anthropic_api_key) | No\* | - | -| `prompt` | Instructions for Claude. Can be a direct prompt or custom template for automation workflows | No | - | -| `track_progress` | Force tag mode with tracking comments. Only works with specific PR/issue events. Preserves GitHub context | No | `false` | -| `claude_args` | Additional arguments to pass directly to Claude CLI (e.g., `--max-turns 10 --model claude-4-0-sonnet-20250805`) | No | "" | -| `base_branch` | The base branch to use for creating new branches (e.g., 'main', 'develop') | No | - | -| `use_sticky_comment` | Use just one comment to deliver PR comments (only applies for pull_request event workflows) | No | `false` | -| `github_token` | GitHub token for Claude to operate with. **Only include this if you're connecting a custom GitHub app of your own!** | No | - | -| `use_bedrock` | Use Amazon Bedrock with OIDC authentication instead of direct Anthropic API | No | `false` | -| `use_vertex` | Use Google Vertex AI with OIDC authentication instead of direct Anthropic API | No | `false` | -| `mcp_config` | Additional MCP configuration (JSON string) that merges with the built-in GitHub MCP servers | No | "" | -| `assignee_trigger` | The assignee username that triggers the action (e.g. @claude). Only used for issue assignment | No | - | -| `label_trigger` | The label name that triggers the action when applied to an issue (e.g. "claude") | No | - | -| `trigger_phrase` | The trigger phrase to look for in comments, issue/PR bodies, and issue titles | No | `@claude` | -| `branch_prefix` | The prefix to use for Claude branches (defaults to 'claude/', use 'claude-' for dash format) | No | `claude/` | -| `settings` | Claude Code settings as JSON string or path to settings JSON file | No | "" | -| `additional_permissions` | Additional permissions to enable. Currently supports 'actions: read' for viewing workflow results | No | "" | -| `experimental_allowed_domains` | Restrict network access to these domains only (newline-separated). | No | "" | -| `use_commit_signing` | Enable commit signing using GitHub's commit signature verification. When false, Claude uses standard git commands | No | `false` | -| `bot_id` | GitHub user ID to use for git operations (defaults to Claude's bot ID) | No | `41898282` | -| `bot_name` | GitHub username to use for git operations (defaults to Claude's bot name) | No | `claude[bot]` | -| `allowed_bots` | Comma-separated list of allowed bot usernames, or '\*' to allow all bots. Empty string (default) allows no bots | No | "" | -| `allowed_non_write_users` | **⚠️ RISKY**: Comma-separated list of usernames to allow without write permissions, or '\*' for all users. Only works with `github_token` input. See [Security](./security.md) | No | "" | +| Input | Description | Required | Default | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------- | +| `anthropic_api_key` | Anthropic API key (required for direct API, not needed for Bedrock/Vertex) | No\* | - | +| `claude_code_oauth_token` | Claude Code OAuth token (alternative to anthropic_api_key) | No\* | - | +| `prompt` | Instructions for Claude. Can be a direct prompt or custom template for automation workflows | No | - | +| `track_progress` | Force tag mode with tracking comments. Only works with specific PR/issue events. Preserves GitHub context | No | `false` | +| `claude_args` | Additional arguments to pass directly to Claude CLI (e.g., `--max-turns 10 --model claude-4-0-sonnet-20250805`) | No | "" | +| `base_branch` | The base branch to use for creating new branches (e.g., 'main', 'develop') | No | - | +| `use_sticky_comment` | Use just one comment to deliver PR comments (only applies for pull_request event workflows) | No | `false` | +| `github_token` | GitHub token for Claude to operate with. **Only include this if you're connecting a custom GitHub app of your own!** | No | - | +| `use_bedrock` | Use Amazon Bedrock with OIDC authentication instead of direct Anthropic API | No | `false` | +| `use_vertex` | Use Google Vertex AI with OIDC authentication instead of direct Anthropic API | No | `false` | +| `mcp_config` | Additional MCP configuration (JSON string) that merges with the built-in GitHub MCP servers | No | "" | +| `assignee_trigger` | The assignee username that triggers the action (e.g. @claude). Only used for issue assignment | No | - | +| `label_trigger` | The label name that triggers the action when applied to an issue (e.g. "claude") | No | - | +| `trigger_phrase` | The trigger phrase to look for in comments, issue/PR bodies, and issue titles | No | `@claude` | +| `branch_prefix` | The prefix to use for Claude branches (defaults to 'claude/', use 'claude-' for dash format) | No | `claude/` | +| `settings` | Claude Code settings as JSON string or path to settings JSON file | No | "" | +| `additional_permissions` | Additional permissions to enable. Currently supports 'actions: read' for viewing workflow results | No | "" | +| `experimental_allowed_domains` | Restrict network access to these domains only (newline-separated). | No | "" | +| `use_commit_signing` | Enable commit signing using GitHub's commit signature verification. When false, Claude uses standard git commands | No | `false` | +| `bot_id` | GitHub user ID to use for git operations (defaults to Claude's bot ID) | No | `41898282` | +| `bot_name` | GitHub username to use for git operations (defaults to Claude's bot name) | No | `claude[bot]` | +| `allowed_bots` | Comma-separated list of allowed bot usernames, or '\*' to allow all bots. Empty string (default) allows no bots | No | "" | +| `allowed_non_write_users` | **⚠️ RISKY**: Comma-separated list of usernames to allow without write permissions, or '\*' for all users. Only works with `github_token` input. See [Security](./security.md) | No | "" | +| `path_to_claude_code_executable` | Optional path to a custom Claude Code executable. Skips automatic installation. Useful for Nix, custom containers, or specialized environments | No | "" | +| `path_to_bun_executable` | Optional path to a custom Bun executable. Skips automatic Bun installation. Useful for Nix, custom containers, or specialized environments | No | "" | ### Deprecated Inputs