Claude Code GitHub Action Configuration Guide

This skill helps you properly configure the anthropics/claude-code-action GitHub Action, avoiding common pitfalls with inputs and CLI flags.

Key Concept: Action Inputs vs CLI Flags

The most common mistake is confusing action inputs with CLI flags. They are NOT interchangeable.

• Action inputs: Defined in workflow YAML directly under with:
• CLI flags: Must be passed through the claude_args input

Common Mistake: Invalid Direct Inputs

These parameters look like they should work as action inputs, but they will be ignored with warnings:

# ❌ WRONG - These are NOT valid action inputs
- uses: anthropics/claude-code-action@v1
  with:
    model: claude-opus-4-5-20251101           # ❌ Ignored
    allowed_tools: "Bash(bun *)"              # ❌ Ignored
    append_system_prompt: "Your prompt"       # ❌ Ignored

Correct Approach: Use claude_args

Pass CLI flags through the claude_args input:

# ✅ CORRECT - Pass CLI flags via claude_args
- uses: anthropics/claude-code-action@v1
  with:
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

    claude_args: >-
      --model claude-opus-4-5-20251101
      --allowedTools "Bash(bun *)"
      --append-system-prompt "After making code changes, run tests."
      --debug

Complete Working Example

name: Claude Code

on:
  issue_comment:
    types: [created]
  issues:
    types: [opened, assigned, labeled]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'issues' && (github.event.action == 'assigned' || github.event.action == 'labeled')) ||
      github.event_name == 'pull_request_review_comment'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      actions: read
    steps:
      - name: Run Claude Code
        uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

          # Valid action inputs
          trigger_phrase: "@claude"
          use_sticky_comment: true
          additional_permissions: |
            actions: read

          # CLI flags via claude_args
          claude_args: >-
            --model claude-opus-4-5-20251101
            --allowedTools "Bash(bun *)"
            --append-system-prompt "Run 'bun run build' after making changes."
            --debug

Valid Action Inputs Reference

These inputs can be used directly under with::

Authentication

Triggers

Branching

Access Control

Configuration

Providers

Features

CLI Flags for claude_args

Common CLI flags to pass via claude_args:

Pattern Matching for --allowedTools

The --allowedTools flag uses pattern matching:

claude_args: >-
  --allowedTools "Bash(bun *)"      # Any bun command
  --allowedTools "Bash(npm run *)"  # Any npm run script
  --allowedTools "Bash(git add *)"  # Git add commands

Pattern Syntax

• * matches any characters: Bash(bun *) matches bun install, bun run build, etc.
• Specific commands: Bash(git commit -m *) matches only git commit with message
• Multiple patterns: Use separate --allowedTools flags for each pattern

Troubleshooting

"Input not defined" Warnings

If you see warnings about undefined inputs, you're likely using CLI flags as direct inputs. Move them to claude_args.

Model Not Changing

Ensure you're using --model inside claude_args, not as a direct input:

# ❌ Wrong
model: claude-opus-4-5-20251101

# ✅ Correct
claude_args: --model claude-opus-4-5-20251101

allowedTools Not Working

Check the pattern syntax and ensure it's in claude_args:

# ❌ Wrong - not valid action input
allowed_tools: "Bash(bun *)"

# ✅ Correct - in claude_args with proper flag name
claude_args: --allowedTools "Bash(bun *)"

Additional Resources

• Claude Code CLI Reference
• claude-code-action Repository