claude-code-action/docs/migration-guide.md

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
mcp_config	claude_args: --mcp-config	Pass MCP config via CLI arguments

Migration Examples

Basic Interactive Workflow (@claude mentions)

Before (v0.x):

- 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):

- 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):

- 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):

- 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):

- 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):

- 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):

- uses: anthropics/claude-code-action@beta
  with:
    claude_env: |
      NODE_ENV: test
      CI: true

After (v1.0):

- 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:

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"
  --mcp-config '{"mcpServers": {"custom": {"command": "npx", "args": ["-y", "@example/server"]}}}'

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"
--mcp-config	Add MCP server config	--mcp-config '{"mcpServers": {...}}'

Provider-Specific Updates

AWS Bedrock

- uses: anthropics/claude-code-action@v1
  with:
    use_bedrock: "true"
    claude_args: |
      --model anthropic.claude-4-0-sonnet-20250805-v1:0

Google Vertex AI

- uses: anthropics/claude-code-action@v1
  with:
    use_vertex: "true"
    claude_args: |
      --model claude-4-0-sonnet@20250805

MCP Configuration Migration

Adding Custom MCP Servers

Before (v0.x):

- uses: anthropics/claude-code-action@beta
  with:
    mcp_config: |
      {
        "mcpServers": {
          "custom-server": {
            "command": "npx",
            "args": ["-y", "@example/server"]
          }
        }
      }

After (v1.0):

- uses: anthropics/claude-code-action@v1
  with:
    claude_args: |
      --mcp-config '{"mcpServers": {"custom-server": {"command": "npx", "args": ["-y", "@example/server"]}}}'

You can also pass MCP configuration from a file:

- uses: anthropics/claude-code-action@v1
  with:
    claude_args: |
      --mcp-config /path/to/mcp-config.json

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
• Move mcp_config to claude_args with --mcp-config
• Test workflow in a non-production environment

Getting Help

If you encounter issues during migration:

1. Check the FAQ for common questions
2. Review example workflows for reference
3. Open an issue 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