From b903a6e4452cb44ec99a4fbe341f4da2f8c9e9d8 Mon Sep 17 00:00:00 2001 From: km-anthropic Date: Thu, 21 Aug 2025 13:34:38 -0700 Subject: [PATCH] docs: Update documentation for v1.0 release (#476) * docs: Update documentation for v1.0 release - Integrate breaking changes naturally without alarming users - Replace deprecated inputs (direct_prompt, custom_instructions, mode) with new unified approach - Update all examples to use prompt and claude_args instead of deprecated inputs - Add migration guides to help users transition from v0.x to v1.0 - Emphasize automatic mode detection as a key feature - Update all workflow examples to @v1 from @beta - Document how claude_args provides direct CLI control - Update FAQ with automatic mode detection explanation - Convert all tool configuration to use claude_args format * fix: Apply prettier formatting to documentation files * fix: Update all Claude model versions to latest and improve documentation accuracy - Update all model references to claude-4-0-sonnet-20250805 (latest Sonnet 4) - Update Bedrock models to anthropic.claude-4-0-sonnet-20250805-v1:0 - Update Vertex models to claude-4-0-sonnet@20250805 - Fix cloud-providers.md to use claude_args instead of deprecated model input - Ensure all examples use @v1 instead of @beta - Keep claude-opus-4-1-20250805 in examples where Opus is demonstrated - Align all documentation with v1.0 patterns consistently * feat: Add dedicated migration guide as requested in PR feedback - Create comprehensive migration-guide.md with step-by-step instructions - Add prominent links to migration guide in README.md - Update usage.md to reference the separate migration guide - Include before/after examples for all common scenarios - Add checklist for systematic migration - Address Ashwin's feedback about having a separate, clearly linked migration guide --- README.md | 18 +-- docs/cloud-providers.md | 22 +-- docs/configuration.md | 89 ++++++++--- docs/custom-automations.md | 62 +++++--- docs/experimental.md | 65 ++++---- docs/faq.md | 52 +++++-- docs/migration-guide.md | 219 +++++++++++++++++++++++++++ docs/usage.md | 169 ++++++++++++++++----- examples/claude-args-example.yml | 6 +- examples/claude-auto-review.yml | 5 +- examples/claude-modes.yml | 34 ++--- examples/claude.yml | 29 ++-- examples/workflow-dispatch-agent.yml | 5 +- 13 files changed, 580 insertions(+), 195 deletions(-) create mode 100644 docs/migration-guide.md diff --git a/README.md b/README.md index ce976ef..32c29d6 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,11 @@ # Claude Code Action -A general-purpose [Claude Code](https://claude.ai/code) action for GitHub PRs and issues that can answer questions and implement code changes. This action listens for a trigger phrase in comments and activates Claude act on the request. It supports multiple authentication methods including Anthropic direct API, Amazon Bedrock, and Google Vertex AI. +A general-purpose [Claude Code](https://claude.ai/code) action for GitHub PRs and issues that can answer questions and implement code changes. This action intelligently detects when to activate based on your workflow context—whether responding to @claude mentions, issue assignments, or executing automation tasks with explicit prompts. It supports multiple authentication methods including Anthropic direct API, Amazon Bedrock, and Google Vertex AI. ## Features +- 🎯 **Intelligent Mode Detection**: Automatically selects the appropriate execution mode based on your workflow context—no configuration needed - 🤖 **Interactive Code Assistant**: Claude can answer questions about code, architecture, and programming - 🔍 **Code Review**: Analyzes PR changes and suggests improvements - ✨ **Code Implementation**: Can implement simple fixes, refactoring, and even new features @@ -13,19 +14,11 @@ A general-purpose [Claude Code](https://claude.ai/code) action for GitHub PRs an - 🛠️ **Flexible Tool Access**: Access to GitHub APIs and file operations (additional tools can be enabled via configuration) - 📋 **Progress Tracking**: Visual progress indicators with checkboxes that dynamically update as Claude completes tasks - 🏃 **Runs on Your Infrastructure**: The action executes entirely on your own GitHub runner (Anthropic API calls go to your chosen provider) +- ⚙️ **Simplified Configuration**: Unified `prompt` and `claude_args` inputs provide clean, powerful configuration aligned with Claude Code SDK -## ⚠️ **BREAKING CHANGES COMING IN v1.0** ⚠️ +## 📦 Upgrading from v0.x? -**We're planning a major update that will significantly change how this action works.** The new version will: - -- ✨ Automatically select the appropriate mode (no more `mode` input) -- 🔧 Simplify configuration with unified `prompt` and `claude_args` -- 🚀 Align more closely with the Claude Code SDK capabilities -- 💥 Remove multiple inputs like `direct_prompt`, `custom_instructions`, and others - -**[→ Read the full v1.0 roadmap and provide feedback](https://github.com/anthropics/claude-code-action/discussions/428)** - ---- +**See our [Migration Guide](./docs/migration-guide.md)** for step-by-step instructions on updating your workflows to v1.0. The new version simplifies configuration while maintaining compatibility with most existing setups. ## Quickstart @@ -40,6 +33,7 @@ This command will guide you through setting up the GitHub app and required secre ## Documentation +- **[Migration Guide](./docs/migration-guide.md)** - **⭐ Upgrading from v0.x to v1.0** - [Setup Guide](./docs/setup.md) - Manual setup, custom GitHub apps, and security best practices - [Usage Guide](./docs/usage.md) - Basic usage, workflow configuration, and input parameters - [Custom Automations](./docs/custom-automations.md) - Examples of automated workflows and custom prompts diff --git a/docs/cloud-providers.md b/docs/cloud-providers.md index 1f9264e..c42fe58 100644 --- a/docs/cloud-providers.md +++ b/docs/cloud-providers.md @@ -20,23 +20,25 @@ Use provider-specific model names based on your chosen provider: ```yaml # For direct Anthropic API (default) -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} # ... other inputs # For Amazon Bedrock with OIDC -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: - model: "anthropic.claude-3-7-sonnet-20250219-beta:0" # Cross-region inference use_bedrock: "true" + claude_args: | + --model anthropic.claude-4-0-sonnet-20250805-v1:0 # ... other inputs # For Google Vertex AI with OIDC -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: - model: "claude-3-7-sonnet@20250219" use_vertex: "true" + claude_args: | + --model claude-4-0-sonnet@20250805 # ... other inputs ``` @@ -59,10 +61,11 @@ Both AWS Bedrock and GCP Vertex AI require OIDC authentication. app-id: ${{ secrets.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: - model: "anthropic.claude-3-7-sonnet-20250219-beta:0" use_bedrock: "true" + claude_args: | + --model anthropic.claude-4-0-sonnet-20250805-v1:0 # ... other inputs permissions: @@ -84,10 +87,11 @@ Both AWS Bedrock and GCP Vertex AI require OIDC authentication. app-id: ${{ secrets.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: - model: "claude-3-7-sonnet@20250219" use_vertex: "true" + claude_args: | + --model claude-4-0-sonnet@20250805 # ... other inputs permissions: diff --git a/docs/configuration.md b/docs/configuration.md index 33dfff5..d85ea56 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -160,33 +160,38 @@ jobs: ## Custom Environment Variables -You can pass custom environment variables to Claude Code execution using the `claude_env` input. This is useful for CI/test setups that require specific environment variables: +You can pass custom environment variables to Claude Code execution using the `settings` input. This is useful for CI/test setups that require specific environment variables: ```yaml -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: - claude_env: | - NODE_ENV: test - CI: true - DATABASE_URL: postgres://test:test@localhost:5432/test_db + settings: | + { + "env": { + "NODE_ENV": "test", + "CI": "true", + "DATABASE_URL": "postgres://test:test@localhost:5432/test_db" + } + } # ... other inputs ``` -The `claude_env` input accepts YAML format where each line defines a key-value pair. These environment variables will be available to Claude Code during execution, allowing it to run tests, build processes, or other commands that depend on specific environment configurations. +These environment variables will be available to Claude Code during execution, allowing it to run tests, build processes, or other commands that depend on specific environment configurations. ## Limiting Conversation Turns -You can use the `max_turns` parameter to limit the number of back-and-forth exchanges Claude can have during task execution. This is useful for: +You can limit the number of back-and-forth exchanges Claude can have during task execution using the `claude_args` input. This is useful for: - Controlling costs by preventing runaway conversations - Setting time boundaries for automated workflows - Ensuring predictable behavior in CI/CD pipelines ```yaml -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - max_turns: "5" # Limit to 5 conversation turns + claude_args: | + --max-turns 5 # Limit to 5 conversation turns # ... other inputs ``` @@ -200,28 +205,50 @@ By default, Claude only has access to: - Comment management (creating/updating comments) - Basic GitHub operations -Claude does **not** have access to execute arbitrary Bash commands by default. If you want Claude to run specific commands (e.g., npm install, npm test), you must explicitly allow them using the `allowed_tools` configuration: +Claude does **not** have access to execute arbitrary Bash commands by default. If you want Claude to run specific commands (e.g., npm install, npm test), you must explicitly allow them using the `claude_args` configuration: -**Note**: If your repository has a `.mcp.json` file in the root directory, Claude will automatically detect and use the MCP server tools defined there. However, these tools still need to be explicitly allowed via the `allowed_tools` configuration. +**Note**: If your repository has a `.mcp.json` file in the root directory, Claude will automatically detect and use the MCP server tools defined there. However, these tools still need to be explicitly allowed. ```yaml -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: - allowed_tools: "Bash(npm install),Bash(npm run test),Edit,Replace,NotebookEditCell" - disallowed_tools: "TaskOutput,KillTask" + claude_args: | + --allowedTools "Bash(npm install),Bash(npm run test),Edit,Replace,NotebookEditCell" + --disallowedTools "TaskOutput,KillTask" # ... other inputs ``` -**Note**: The base GitHub tools are always included. Use `allowed_tools` to add additional tools (including specific Bash commands), and `disallowed_tools` to prevent specific tools from being used. +**Note**: The base GitHub tools are always included. Use `--allowedTools` to add additional tools (including specific Bash commands), and `--disallowedTools` to prevent specific tools from being used. ## Custom Model -Use a specific Claude model: +Specify a Claude model using `claude_args`: ```yaml -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: - # model: "claude-3-5-sonnet-20241022" # Optional: specify a different model + claude_args: | + --model claude-4-0-sonnet-20250805 + # ... other inputs +``` + +For provider-specific models: + +```yaml +# AWS Bedrock +- uses: anthropics/claude-code-action@v1 + with: + use_bedrock: "true" + claude_args: | + --model anthropic.claude-4-0-sonnet-20250805-v1:0 + # ... other inputs + +# Google Vertex AI +- uses: anthropics/claude-code-action@v1 + with: + use_vertex: "true" + claude_args: | + --model claude-4-0-sonnet@20250805 # ... other inputs ``` @@ -232,7 +259,7 @@ You can provide Claude Code settings to customize behavior such as model selecti ### Option 1: Settings File ```yaml -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: settings: "path/to/settings.json" # ... other inputs @@ -241,7 +268,7 @@ You can provide Claude Code settings to customize behavior such as model selecti ### Option 2: Inline Settings ```yaml -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: settings: | { @@ -280,6 +307,20 @@ For a complete list of available settings and their descriptions, see the [Claud **Notes**: - The `enableAllProjectMcpServers` setting is always set to `true` by this action to ensure MCP servers work correctly. -- If both the `model` input parameter and a `model` in settings are provided, the `model` input parameter takes precedence. -- The `allowed_tools` and `disallowed_tools` input parameters take precedence over `permissions` in settings. -- In a future version, we may deprecate individual input parameters in favor of using the settings file for all configuration. +- The `claude_args` input provides direct access to Claude Code CLI arguments and takes precedence over settings. +- We recommend using `claude_args` for simple configurations and `settings` for complex configurations with hooks and environment variables. + +## Migration from Deprecated Inputs + +Many individual input parameters have been consolidated into `claude_args` or `settings`. Here's how to migrate: + +| Old Input | New Approach | +| --------------------- | -------------------------------------------------------- | +| `allowed_tools` | Use `claude_args: "--allowedTools Tool1,Tool2"` | +| `disallowed_tools` | Use `claude_args: "--disallowedTools Tool1,Tool2"` | +| `max_turns` | Use `claude_args: "--max-turns 10"` | +| `model` | Use `claude_args: "--model claude-4-0-sonnet-20250805"` | +| `claude_env` | Use `settings` with `"env"` object | +| `custom_instructions` | Use `claude_args: "--system-prompt 'Your instructions'"` | +| `direct_prompt` | Use `prompt` input instead | +| `override_prompt` | Use `prompt` with GitHub context variables | diff --git a/docs/custom-automations.md b/docs/custom-automations.md index d3693d4..71824c1 100644 --- a/docs/custom-automations.md +++ b/docs/custom-automations.md @@ -1,6 +1,6 @@ # Custom Automations -These examples show how to configure Claude to act automatically based on GitHub events, without requiring manual @mentions. +These examples show how to configure Claude to act automatically based on GitHub events. When you provide a `prompt` input, the action automatically runs in agent mode without requiring manual @mentions. Without a `prompt`, it runs in interactive mode, responding to @claude mentions. ## Supported GitHub Events @@ -26,14 +26,15 @@ on: - "src/api/**/*.ts" steps: - - uses: anthropics/claude-code-action@beta + - uses: anthropics/claude-code-action@v1 with: - direct_prompt: | + prompt: | Update the API documentation in README.md to reflect the changes made to the API endpoints in this PR. + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} ``` -When API files are modified, Claude automatically updates your README with the latest endpoint documentation and pushes the changes back to the PR, keeping your docs in sync with your code. +When API files are modified, the action automatically detects that a `prompt` is provided and runs in agent mode. Claude updates your README with the latest endpoint documentation and pushes the changes back to the PR, keeping your docs in sync with your code. ## Author-Specific Code Reviews @@ -50,28 +51,26 @@ jobs: github.event.pull_request.user.login == 'developer1' || github.event.pull_request.user.login == 'external-contributor' steps: - - uses: anthropics/claude-code-action@beta + - uses: anthropics/claude-code-action@v1 with: - direct_prompt: | + prompt: | Please provide a thorough review of this pull request. Pay extra attention to coding standards, security practices, and test coverage since this is from an external contributor. + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} ``` -Perfect for automatically reviewing PRs from new team members, external contributors, or specific developers who need extra guidance. +Perfect for automatically reviewing PRs from new team members, external contributors, or specific developers who need extra guidance. The action automatically runs in agent mode when a `prompt` is provided. ## Custom Prompt Templates -Use `override_prompt` for complete control over Claude's behavior with variable substitution: +Use the `prompt` input with GitHub context variables for dynamic automation: ```yaml -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: - override_prompt: | - Analyze PR #$PR_NUMBER in $REPOSITORY for security vulnerabilities. - - Changed files: - $CHANGED_FILES + prompt: | + Analyze PR #${{ github.event.pull_request.number }} in ${{ github.repository }} for security vulnerabilities. Focus on: - SQL injection risks @@ -80,12 +79,35 @@ Use `override_prompt` for complete control over Claude's behavior with variable - Exposed secrets or credentials Provide severity ratings (Critical/High/Medium/Low) for any issues found. + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} ``` -The `override_prompt` feature supports these variables: +You can access any GitHub context variable using the standard GitHub Actions syntax: -- `$REPOSITORY`, `$PR_NUMBER`, `$ISSUE_NUMBER` -- `$PR_TITLE`, `$ISSUE_TITLE`, `$PR_BODY`, `$ISSUE_BODY` -- `$PR_COMMENTS`, `$ISSUE_COMMENTS`, `$REVIEW_COMMENTS` -- `$CHANGED_FILES`, `$TRIGGER_COMMENT`, `$TRIGGER_USERNAME` -- `$BRANCH_NAME`, `$BASE_BRANCH`, `$EVENT_TYPE`, `$IS_PR` +- `${{ github.repository }}` - The repository name +- `${{ github.event.pull_request.number }}` - PR number +- `${{ github.event.issue.number }}` - Issue number +- `${{ github.event.pull_request.title }}` - PR title +- `${{ github.event.pull_request.body }}` - PR description +- `${{ github.event.comment.body }}` - Comment text +- `${{ github.actor }}` - User who triggered the workflow +- `${{ github.base_ref }}` - Base branch for PRs +- `${{ github.head_ref }}` - Head branch for PRs + +## Advanced Configuration with claude_args + +For more control over Claude's behavior, use the `claude_args` input to pass CLI arguments directly: + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + prompt: "Review this PR for performance issues" + claude_args: | + --max-turns 15 + --model claude-4-0-sonnet-20250805 + --allowedTools Edit,Read,Write,Bash + --system-prompt "You are a performance optimization expert. Focus on identifying bottlenecks and suggesting improvements." + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} +``` + +This provides full access to Claude Code CLI capabilities while maintaining the simplified action interface. diff --git a/docs/experimental.md b/docs/experimental.md index e541c9f..545ffbb 100644 --- a/docs/experimental.md +++ b/docs/experimental.md @@ -2,65 +2,66 @@ **Note:** Experimental features are considered unstable and not supported for production use. They may change or be removed at any time. -## Execution Modes +## Automatic Mode Detection -The action supports three execution modes, each optimized for different use cases: +The action intelligently detects the appropriate execution mode based on your workflow context, eliminating the need for manual mode configuration. -### Tag Mode (Default) +### Interactive Mode (Tag Mode) -The traditional implementation mode that responds to @claude mentions, issue assignments, or labels. +Activated when Claude detects @mentions, issue assignments, or labels—without an explicit `prompt`. -- **Triggers**: `@claude` mentions, issue assignment, label application +- **Triggers**: `@claude` mentions in comments, issue assignment to claude user, label application - **Features**: Creates tracking comments with progress checkboxes, full implementation capabilities -- **Use case**: General-purpose code implementation and Q&A +- **Use case**: Interactive code assistance, Q&A, and implementation requests ```yaml -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - # mode: tag is the default + # No prompt needed - responds to @claude mentions ``` -### Agent Mode +### Automation Mode (Agent Mode) -**Note: Agent mode is currently in active development and may undergo breaking changes.** +Automatically activated when you provide a `prompt` input. -For direct automation when an explicit prompt is provided. - -- **Triggers**: Works with any event when `prompt` input is provided -- **Features**: Direct execution without @claude mentions, no tracking comments +- **Triggers**: Any GitHub event when `prompt` input is provided +- **Features**: Direct execution without requiring @claude mentions, streamlined for automation - **Use case**: Automated PR reviews, scheduled tasks, workflow automation ```yaml -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: | Check for outdated dependencies and create an issue if any are found. - # Mode is auto-detected when prompt is provided + # Automatically runs in agent mode when prompt is provided ``` -### Experimental Review Mode +### How It Works -**Warning: This is an experimental feature that may change or be removed at any time.** +The action uses this logic to determine the mode: -For automated code reviews on pull requests. +1. **If `prompt` is provided** → Runs in **agent mode** for automation +2. **If no `prompt` but @claude is mentioned** → Runs in **tag mode** for interaction +3. **If neither** → No action is taken -- **Triggers**: Pull request events (`opened`, `synchronize`) or `@claude review` comments -- **Features**: Provides detailed code reviews with inline comments and suggestions -- **Use case**: Automated PR reviews, code quality checks +This automatic detection ensures your workflows are simpler and more intuitive, without needing to understand or configure different modes. + +### Advanced Mode Control + +For specialized use cases, you can fine-tune behavior using `claude_args`: ```yaml -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: - mode: experimental-review + prompt: "Review this PR" + claude_args: | + --max-turns 20 + --system-prompt "You are a code review specialist" anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - custom_instructions: | - Focus on code quality, security, and best practices. ``` -See [`examples/claude-modes.yml`](../examples/claude-modes.yml) and [`examples/claude-experimental-review-mode.yml`](../examples/claude-experimental-review-mode.yml) for complete examples of each mode. - ## Network Restrictions For enhanced security, you can restrict Claude's network access to specific domains only. This feature is particularly useful for: @@ -76,7 +77,7 @@ When `experimental_allowed_domains` is set, Claude can only access the domains y #### If using Anthropic API or subscription ```yaml -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} # Or: claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} @@ -87,7 +88,7 @@ When `experimental_allowed_domains` is set, Claude can only access the domains y #### If using AWS Bedrock ```yaml -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: use_bedrock: "true" experimental_allowed_domains: | @@ -98,7 +99,7 @@ When `experimental_allowed_domains` is set, Claude can only access the domains y #### If using Google Vertex AI ```yaml -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: use_vertex: "true" experimental_allowed_domains: | @@ -111,7 +112,7 @@ When `experimental_allowed_domains` is set, Claude can only access the domains y In addition to your provider domains, you may need to include GitHub-related domains. For GitHub.com users, common domains include: ```yaml -- uses: anthropics/claude-code-action@beta +- uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} experimental_allowed_domains: | diff --git a/docs/faq.md b/docs/faq.md index 2f03b31..3594111 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -41,10 +41,11 @@ By default, Claude only uses commit tools for non-destructive changes to the bra - Never push to branches other than where it was invoked (either its own branch or the PR branch) - Never force push or perform destructive operations -You can grant additional tools via the `allowed_tools` input if needed: +You can grant additional tools via the `claude_args` input if needed: ```yaml -allowed_tools: "Bash(git rebase:*)" # Use with caution +claude_args: | + --allowedTools "Bash(git rebase:*)" # Use with caution ``` ### Why won't Claude create a pull request? @@ -67,7 +68,7 @@ Yes! Claude can access GitHub Actions workflow runs, job logs, and test results 2. Configure the action with additional permissions: ```yaml - - uses: anthropics/claude-code-action@beta + - uses: anthropics/claude-code-action@v1 with: additional_permissions: | actions: read @@ -105,30 +106,51 @@ If you need full history, you can configure this in your workflow before calling ## Configuration and Tools -### What's the difference between `direct_prompt` and `custom_instructions`? +### How does automatic mode detection work? -These inputs serve different purposes in how Claude responds: +The action intelligently detects whether to run in interactive mode or automation mode: -- **`direct_prompt`**: Bypasses trigger detection entirely. When provided, Claude executes this exact instruction regardless of comments or mentions. Perfect for automated workflows where you want Claude to perform a specific task on every run (e.g., "Update the API documentation based on changes in this PR"). +- **With `prompt` input**: Runs in automation mode - executes immediately without waiting for @claude mentions +- **Without `prompt` input**: Runs in interactive mode - waits for @claude mentions in comments -- **`custom_instructions`**: Additional context added to Claude's system prompt while still respecting normal triggers. These instructions modify Claude's behavior but don't replace the triggering comment. Use this to give Claude standing instructions like "You have been granted additional tools for ...". +This automatic detection eliminates the need to manually configure modes. Example: ```yaml -# Using direct_prompt - runs automatically without @claude mention -direct_prompt: "Review this PR for security vulnerabilities" +# Automation mode - runs automatically +prompt: "Review this PR for security vulnerabilities" +# Interactive mode - waits for @claude mention +# (no prompt provided) +``` -# Using custom_instructions - still requires @claude trigger -custom_instructions: "Focus on performance implications and suggest optimizations" +### What happened to `direct_prompt` and `custom_instructions`? + +**These inputs are deprecated in v1.0:** + +- **`direct_prompt`** → Use `prompt` instead +- **`custom_instructions`** → Use `claude_args` with `--system-prompt` + +Migration examples: + +```yaml +# Old (v0.x) +direct_prompt: "Review this PR" +custom_instructions: "Focus on security" + +# New (v1.0) +prompt: "Review this PR" +claude_args: | + --system-prompt "Focus on security" ``` ### Why doesn't Claude execute my bash commands? -The Bash tool is **disabled by default** for security. To enable individual bash commands: +The Bash tool is **disabled by default** for security. To enable individual bash commands using `claude_args`: ```yaml -allowed_tools: "Bash(npm:*),Bash(git:*)" # Allows only npm and git commands +claude_args: | + --allowedTools "Bash(npm:*),Bash(git:*)" # Allows only npm and git commands ``` ### Can Claude work across multiple repositories? @@ -152,7 +174,7 @@ Claude Code Action automatically configures two MCP servers: 1. **GitHub MCP server**: For GitHub API operations 2. **File operations server**: For advanced file manipulation -However, tools from these servers still need to be explicitly allowed via `allowed_tools`. +However, tools from these servers still need to be explicitly allowed via `claude_args` with `--allowedTools`. ## Troubleshooting @@ -168,7 +190,7 @@ The trigger uses word boundaries, so `@claude` must be a complete word. Variatio 1. **Always specify permissions explicitly** in your workflow file 2. **Use GitHub Secrets** for API keys - never hardcode them -3. **Be specific with `allowed_tools`** - only enable what's necessary +3. **Be specific with tool permissions** - only enable what's necessary via `claude_args` 4. **Test in a separate branch** before using on important PRs 5. **Monitor Claude's token usage** to avoid hitting API limits 6. **Review Claude's changes** carefully before merging diff --git a/docs/migration-guide.md b/docs/migration-guide.md new file mode 100644 index 0000000..fca63a7 --- /dev/null +++ b/docs/migration-guide.md @@ -0,0 +1,219 @@ +# Migration Guide: v0.x to v1.0 + +This guide helps you migrate from Claude Code Action v0.x to v1.0. The new version introduces intelligent mode detection and simplified configuration while maintaining backward compatibility for most use cases. + +## Overview of Changes + +### 🎯 Key Improvements in v1.0 + +1. **Automatic Mode Detection** - No more manual `mode` configuration +2. **Simplified Configuration** - Unified `prompt` and `claude_args` inputs +3. **Better SDK Alignment** - Closer integration with Claude Code CLI + +### ⚠️ Breaking Changes + +The following inputs have been deprecated and replaced: + +| Deprecated Input | Replacement | Notes | +| --------------------- | -------------------------------- | --------------------------------------------- | +| `mode` | Auto-detected | Action automatically chooses based on context | +| `direct_prompt` | `prompt` | Direct drop-in replacement | +| `override_prompt` | `prompt` | Use GitHub context variables instead | +| `custom_instructions` | `claude_args: --system-prompt` | Move to CLI arguments | +| `max_turns` | `claude_args: --max-turns` | Use CLI format | +| `model` | `claude_args: --model` | Specify via CLI | +| `allowed_tools` | `claude_args: --allowedTools` | Use CLI format | +| `disallowed_tools` | `claude_args: --disallowedTools` | Use CLI format | +| `claude_env` | `settings` with env object | Use settings JSON | + +## Migration Examples + +### Basic Interactive Workflow (@claude mentions) + +**Before (v0.x):** + +```yaml +- uses: anthropics/claude-code-action@beta + with: + mode: "tag" + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + custom_instructions: "Follow our coding standards" + max_turns: "10" + allowed_tools: "Edit,Read,Write" +``` + +**After (v1.0):** + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + claude_args: | + --max-turns 10 + --system-prompt "Follow our coding standards" + --allowedTools Edit,Read,Write +``` + +### Automation Workflow + +**Before (v0.x):** + +```yaml +- uses: anthropics/claude-code-action@beta + with: + mode: "agent" + direct_prompt: "Review this PR for security issues" + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + model: "claude-3-5-sonnet-20241022" + allowed_tools: "Edit,Read,Write" +``` + +**After (v1.0):** + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + prompt: "Review this PR for security issues" + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + claude_args: | + --model claude-4-0-sonnet-20250805 + --allowedTools Edit,Read,Write +``` + +### Custom Template with Variables + +**Before (v0.x):** + +```yaml +- uses: anthropics/claude-code-action@beta + with: + override_prompt: | + Analyze PR #$PR_NUMBER in $REPOSITORY + Changed files: $CHANGED_FILES + Focus on security vulnerabilities +``` + +**After (v1.0):** + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + prompt: | + Analyze PR #${{ github.event.pull_request.number }} in ${{ github.repository }} + Focus on security vulnerabilities in the changed files +``` + +### Environment Variables + +**Before (v0.x):** + +```yaml +- uses: anthropics/claude-code-action@beta + with: + claude_env: | + NODE_ENV: test + CI: true +``` + +**After (v1.0):** + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + settings: | + { + "env": { + "NODE_ENV": "test", + "CI": "true" + } + } +``` + +## How Mode Detection Works + +The action now automatically detects the appropriate mode: + +1. **If `prompt` is provided** → Runs in **automation mode** + + - Executes immediately without waiting for @claude mentions + - Perfect for scheduled tasks, PR automation, etc. + +2. **If no `prompt` but @claude is mentioned** → Runs in **interactive mode** + + - Waits for and responds to @claude mentions + - Creates tracking comments with progress + +3. **If neither** → No action is taken + +## Advanced Configuration with claude_args + +The `claude_args` input provides direct access to Claude Code CLI arguments: + +```yaml +claude_args: | + --max-turns 15 + --model claude-4-0-sonnet-20250805 + --allowedTools Edit,Read,Write,Bash + --disallowedTools WebSearch + --system-prompt "You are a senior engineer focused on code quality" +``` + +### Common claude_args Options + +| Option | Description | Example | +| ------------------- | ------------------------ | ------------------------------------- | +| `--max-turns` | Limit conversation turns | `--max-turns 10` | +| `--model` | Specify Claude model | `--model claude-4-0-sonnet-20250805` | +| `--allowedTools` | Enable specific tools | `--allowedTools Edit,Read,Write` | +| `--disallowedTools` | Disable specific tools | `--disallowedTools WebSearch` | +| `--system-prompt` | Add system instructions | `--system-prompt "Focus on security"` | + +## Provider-Specific Updates + +### AWS Bedrock + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + use_bedrock: "true" + claude_args: | + --model anthropic.claude-4-0-sonnet-20250805-v1:0 +``` + +### Google Vertex AI + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + use_vertex: "true" + claude_args: | + --model claude-4-0-sonnet@20250805 +``` + +## Step-by-Step Migration Checklist + +- [ ] Update action version from `@beta` to `@v1` +- [ ] Remove `mode` input (auto-detected now) +- [ ] Replace `direct_prompt` with `prompt` +- [ ] Replace `override_prompt` with `prompt` using GitHub context +- [ ] Move `custom_instructions` to `claude_args` with `--system-prompt` +- [ ] Convert `max_turns` to `claude_args` with `--max-turns` +- [ ] Convert `model` to `claude_args` with `--model` +- [ ] Convert `allowed_tools` to `claude_args` with `--allowedTools` +- [ ] Convert `disallowed_tools` to `claude_args` with `--disallowedTools` +- [ ] Move `claude_env` to `settings` JSON format +- [ ] Test workflow in a non-production environment + +## Getting Help + +If you encounter issues during migration: + +1. Check the [FAQ](./faq.md) for common questions +2. Review [example workflows](../examples/) for reference +3. Open an [issue](https://github.com/anthropics/claude-code-action/issues) for support + +## Version Compatibility + +- **v0.x workflows** will continue to work but with deprecation warnings +- **v1.0** is the recommended version for all new workflows +- Future versions may remove deprecated inputs entirely diff --git a/docs/usage.md b/docs/usage.md index 7e77080..c90b693 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -18,27 +18,26 @@ jobs: claude-response: runs-on: ubuntu-latest steps: - - uses: anthropics/claude-code-action@beta + - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} # Or use OAuth token instead: # claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} - github_token: ${{ secrets.GITHUB_TOKEN }} - # Optional: set execution mode (default: tag) - # mode: "tag" + + # Optional: provide a prompt for automation workflows + # prompt: "Review this PR for security issues" + + # Optional: pass advanced arguments to Claude CLI + # claude_args: | + # --max-turns 10 + # --model claude-4-0-sonnet-20250805 + # Optional: add custom trigger phrase (default: @claude) # trigger_phrase: "/claude" # Optional: add assignee trigger for issues # assignee_trigger: "claude" # Optional: add label trigger for issues # label_trigger: "claude" - # Optional: add custom environment variables (YAML format) - # claude_env: | - # NODE_ENV: test - # DEBUG: true - # API_URL: https://api.example.com - # Optional: limit the number of conversation turns - # max_turns: "5" # Optional: grant additional permissions (requires corresponding GitHub token permissions) # additional_permissions: | # actions: read @@ -48,42 +47,128 @@ jobs: ## Inputs -| Input | Description | Required | Default | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | -| `mode` | Execution mode: 'tag' (default - triggered by mentions/assignments), 'agent' (for automation), 'experimental-review' (for PR reviews) | No | `tag` | -| `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\* | - | -| `direct_prompt` | Direct prompt for Claude to execute automatically without needing a trigger (for automated workflows) | No | - | -| `override_prompt` | Complete replacement of Claude's prompt with custom template (supports variable substitution) | No | - | -| `base_branch` | The base branch to use for creating new branches (e.g., 'main', 'develop') | No | - | -| `max_turns` | Maximum number of conversation turns Claude can take (limits back-and-forth exchanges) | No | - | -| `timeout_minutes` | Timeout in minutes for execution | No | `30` | -| `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 | - | -| `model` | Model to use (provider-specific format required for Bedrock/Vertex) | No | - | -| `fallback_model` | Enable automatic fallback to specified model when primary model is unavailable | No | - | -| `anthropic_model` | **DEPRECATED**: Use `model` instead. Kept for backward compatibility. | 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` | -| `allowed_tools` | Additional tools for Claude to use (the base GitHub tools will always be included) | No | "" | -| `disallowed_tools` | Tools that Claude should never use | No | "" | -| `custom_instructions` | Additional custom instructions to include in the prompt for Claude | No | "" | -| `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/` | -| `claude_env` | Custom environment variables to pass to Claude Code execution (YAML format) | No | "" | -| `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` | -| `allowed_bots` | Comma-separated list of allowed bot usernames, or '\*' to allow all bots. Empty string (default) allows no bots | 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 | - | +| `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 | - | +| `timeout_minutes` | Timeout in minutes for execution | No | `30` | +| `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` | +| `allowed_bots` | Comma-separated list of allowed bot usernames, or '\*' to allow all bots. Empty string (default) allows no bots | No | "" | + +### Deprecated Inputs + +These inputs are deprecated and will be removed in a future version: + +| Input | Description | Migration Path | +| --------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | +| `mode` | **DEPRECATED**: Mode is now automatically detected based on workflow context | Remove this input; the action auto-detects the correct mode | +| `direct_prompt` | **DEPRECATED**: Use `prompt` instead | Replace with `prompt` | +| `override_prompt` | **DEPRECATED**: Use `prompt` with template variables or `claude_args` with `--system-prompt` | Use `prompt` for templates or `claude_args` for system prompts | +| `custom_instructions` | **DEPRECATED**: Use `claude_args` with `--system-prompt` or include in `prompt` | Move instructions to `prompt` or use `claude_args` | +| `max_turns` | **DEPRECATED**: Use `claude_args` with `--max-turns` instead | Use `claude_args: "--max-turns 5"` | +| `model` | **DEPRECATED**: Use `claude_args` with `--model` instead | Use `claude_args: "--model claude-4-0-sonnet-20250805"` | +| `fallback_model` | **DEPRECATED**: Use `claude_args` with fallback configuration | Configure fallback in `claude_args` or `settings` | +| `allowed_tools` | **DEPRECATED**: Use `claude_args` with `--allowedTools` instead | Use `claude_args: "--allowedTools Edit,Read,Write"` | +| `disallowed_tools` | **DEPRECATED**: Use `claude_args` with `--disallowedTools` instead | Use `claude_args: "--disallowedTools WebSearch"` | +| `claude_env` | **DEPRECATED**: Use `settings` with env configuration | Configure environment in `settings` JSON | \*Required when using direct Anthropic API (default and when not using Bedrock or Vertex) > **Note**: This action is currently in beta. Features and APIs may change as we continue to improve the integration. +## Upgrading from v0.x? + +For a comprehensive guide on migrating from v0.x to v1.0, including step-by-step instructions and examples, see our **[Migration Guide](./migration-guide.md)**. + +### Quick Migration Examples + +#### Interactive Workflows (with @claude mentions) + +**Before (v0.x):** + +```yaml +- uses: anthropics/claude-code-action@beta + with: + mode: "tag" + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + custom_instructions: "Focus on security" + max_turns: "10" +``` + +**After (v1.0):** + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + claude_args: | + --max-turns 10 + --system-prompt "Focus on security" +``` + +#### Automation Workflows + +**Before (v0.x):** + +```yaml +- uses: anthropics/claude-code-action@beta + with: + mode: "agent" + direct_prompt: "Update the API documentation" + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + model: "claude-4-0-sonnet-20250805" + allowed_tools: "Edit,Read,Write" +``` + +**After (v1.0):** + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + prompt: "Update the API documentation" + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + claude_args: | + --model claude-4-0-sonnet-20250805 + --allowedTools Edit,Read,Write +``` + +#### Custom Templates + +**Before (v0.x):** + +```yaml +- uses: anthropics/claude-code-action@beta + with: + override_prompt: | + Analyze PR #$PR_NUMBER for security issues. + Focus on: $CHANGED_FILES +``` + +**After (v1.0):** + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + prompt: | + Analyze PR #${{ github.event.pull_request.number }} for security issues. + Focus on the changed files in this PR. +``` + ## Ways to Tag @claude These examples show how to interact with Claude using comments in PRs and issues. By default, Claude will be triggered anytime you mention `@claude`, but you can customize the exact trigger phrase using the `trigger_phrase` input in the workflow. diff --git a/examples/claude-args-example.yml b/examples/claude-args-example.yml index 1c9b8f5..91d27bf 100644 --- a/examples/claude-args-example.yml +++ b/examples/claude-args-example.yml @@ -17,13 +17,11 @@ jobs: - name: Run Claude with custom arguments uses: anthropics/claude-code-action@v1 with: - mode: agent prompt: ${{ github.event.inputs.prompt }} anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - # New claudeArgs input allows direct CLI argument control - # Order: -p [claudeArgs] [legacy options] [BASE_ARGS] - # Note: BASE_ARGS (--verbose --output-format stream-json) cannot be overridden + # claude_args provides direct CLI argument control + # This allows full customization of Claude's behavior claude_args: | --max-turns 15 --model claude-opus-4-1-20250805 diff --git a/examples/claude-auto-review.yml b/examples/claude-auto-review.yml index 3d5399e..6fa4111 100644 --- a/examples/claude-auto-review.yml +++ b/examples/claude-auto-review.yml @@ -35,4 +35,7 @@ jobs: Provide constructive feedback with specific suggestions for improvement. Use inline comments to highlight specific areas of concern. - # allowed_tools: "mcp__github__create_pending_pull_request_review,mcp__github__add_comment_to_pending_review,mcp__github__submit_pending_pull_request_review,mcp__github__get_pull_request_diff" + + # Optional: Configure specific tools for review operations + # claude_args: | + # --allowedTools "mcp__github__create_pending_pull_request_review,mcp__github__add_comment_to_pending_review,mcp__github__submit_pending_pull_request_review,mcp__github__get_pull_request_diff" diff --git a/examples/claude-modes.yml b/examples/claude-modes.yml index 4d1033e..03304a0 100644 --- a/examples/claude-modes.yml +++ b/examples/claude-modes.yml @@ -1,21 +1,21 @@ -name: Claude Mode Examples +name: Claude Automatic Mode Detection Examples on: - # Events for tag mode + # Events for interactive mode (responds to @claude mentions) issue_comment: types: [created] issues: types: [opened, labeled] pull_request: types: [opened] - # Events for agent mode (only these work with agent mode) + # Events for automation mode (runs with explicit prompt) workflow_dispatch: schedule: - cron: "0 0 * * 0" # Weekly on Sunday jobs: - # Tag Mode (Default) - Traditional implementation - tag-mode-example: + # Interactive Mode - Activated automatically when no prompt is provided + interactive-mode-example: runs-on: ubuntu-latest permissions: contents: write @@ -23,18 +23,17 @@ jobs: issues: write id-token: write steps: - - uses: anthropics/claude-code-action@beta + - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - # Tag mode (default) behavior: + # Interactive mode (auto-detected when no prompt): # - Scans for @claude mentions in comments, issues, and PRs # - Only acts when trigger phrase is found # - Creates tracking comments with progress checkboxes # - Perfect for: Interactive Q&A, on-demand code changes - # Agent Mode - Automation for workflow_dispatch and schedule events - agent-mode-scheduled-task: - # Only works with workflow_dispatch or schedule events + # Automation Mode - Activated automatically when prompt is provided + automation-mode-scheduled-task: runs-on: ubuntu-latest permissions: contents: write @@ -42,15 +41,14 @@ jobs: issues: write id-token: write steps: - - uses: anthropics/claude-code-action@beta + - uses: anthropics/claude-code-action@v1 with: - mode: agent anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - override_prompt: | + prompt: | Check for outdated dependencies and security vulnerabilities. Create an issue if any critical problems are found. - # Agent mode behavior: - # - ONLY works with workflow_dispatch and schedule events - # - Does NOT work with pull_request, issues, or issue_comment events - # - No @claude mention needed for supported events - # - Perfect for: scheduled maintenance, manual automation runs + # Automation mode (auto-detected when prompt provided): + # - Works with any GitHub event + # - Executes immediately without waiting for @claude mentions + # - No tracking comments created + # - Perfect for: scheduled maintenance, automated reviews, CI/CD tasks diff --git a/examples/claude.yml b/examples/claude.yml index f2cf262..2075a19 100644 --- a/examples/claude.yml +++ b/examples/claude.yml @@ -32,7 +32,7 @@ jobs: - name: Run Claude Code id: claude - uses: anthropics/claude-code-action@beta + uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} @@ -40,24 +40,23 @@ jobs: additional_permissions: | actions: read - # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4.1) - # model: "claude-opus-4-1-20250805" - # Optional: Customize the trigger phrase (default: @claude) # trigger_phrase: "/claude" # Optional: Trigger when specific user is assigned to an issue # assignee_trigger: "claude-bot" - # Optional: Allow Claude to run specific commands - # allowed_tools: "Bash(npm install),Bash(npm run build),Bash(npm run test:*),Bash(npm run lint:*)" + # Optional: Configure Claude's behavior with CLI arguments + # claude_args: | + # --model claude-opus-4-1-20250805 + # --max-turns 10 + # --allowedTools "Bash(npm install),Bash(npm run build),Bash(npm run test:*),Bash(npm run lint:*)" + # --system-prompt "Follow our coding standards. Ensure all new code has tests. Use TypeScript for new files." - # Optional: Add custom instructions for Claude to customize its behavior for your project - # custom_instructions: | - # Follow our coding standards - # Ensure all new code has tests - # Use TypeScript for new files - - # Optional: Custom environment variables for Claude - # claude_env: | - # NODE_ENV: test + # Optional: Advanced settings configuration + # settings: | + # { + # "env": { + # "NODE_ENV": "test" + # } + # } diff --git a/examples/workflow-dispatch-agent.yml b/examples/workflow-dispatch-agent.yml index 1e72847..4d35912 100644 --- a/examples/workflow-dispatch-agent.yml +++ b/examples/workflow-dispatch-agent.yml @@ -28,11 +28,10 @@ jobs: fetch-depth: 2 # Need at least 2 commits to analyze the latest - name: Run Claude Analysis - uses: anthropics/claude-code-action@beta + uses: anthropics/claude-code-action@v1 with: - mode: agent anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - override_prompt: | + prompt: | Analyze the latest commit in this repository. ${{ github.event.inputs.analysis_type == 'summarize-commit' && 'Task: Provide a clear, concise summary of what changed in the latest commit. Include the commit message, files changed, and the purpose of the changes.' || '' }}