---
name: github-actions
description: Set up and configure Claude Code GitHub Actions for AI-powered automation in your GitHub workflow. Use for creating workflows, troubleshooting, and configuring cloud providers (AWS Bedrock, Google Vertex AI).
argument-hint: "[setup|workflow|troubleshoot|cloud-provider|custom]"
---

You are an expert at configuring Claude Code GitHub Actions. Help users set up, configure, troubleshoot, and optimize their GitHub Actions workflows with Claude integration.

## Quick Setup

The fastest way to set up Claude Code GitHub Actions is through the CLI:

```bash
claude /install-github-app
```

This command guides you through:
- Installing the Claude GitHub App
- Setting up required secrets (ANTHROPIC_API_KEY)
- Creating workflow files in `.github/workflows/`

**Requirements:**
- Must be repository admin
- Direct Claude API user (not Bedrock/Vertex)
- Repository needs Contents, Issues, and Pull requests permissions

## Manual Setup

If `/install-github-app` doesn't work:

1. **Install Claude GitHub App**: https://github.com/apps/claude
   - Grants: Contents (R/W), Issues (R/W), Pull requests (R/W)

2. **Add secret**: `ANTHROPIC_API_KEY` in repository settings → Secrets and variables → Actions

3. **Create workflow file**: `.github/workflows/claude.yml`

```yaml
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
```

## Common Workflow Patterns

### 1. Interactive Mode (Responds to @claude)

```yaml
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # No prompt needed - responds to @claude mentions
```

**Usage in comments:**
```
@claude implement this feature based on the issue description
@claude fix the TypeError in the user dashboard component
@claude review this PR for security issues
```

### 2. Automated Mode with Skills

```yaml
name: Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "/review"
          claude_args: "--max-turns 5"
```

### 3. Scheduled Automation

```yaml
name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Generate a summary of yesterday's commits and open issues"
          claude_args: "--model claude-opus-4-6"
```

## Action Parameters

### Core Parameters

| Parameter           | Description                                            | Required |
|---------------------|--------------------------------------------------------|----------|
| `prompt`            | Instructions or skill (e.g., `/review`)                | No*      |
| `claude_args`       | CLI arguments for Claude Code                          | No       |
| `anthropic_api_key` | Claude API key                                         | Yes**    |
| `github_token`      | GitHub token (auto-provided if not specified)          | No       |
| `trigger_phrase`    | Custom trigger (default: "@claude")                    | No       |
| `use_bedrock`       | Use AWS Bedrock                                        | No       |
| `use_vertex`        | Use Google Vertex AI                                   | No       |

*Prompt optional for interactive mode (responds to trigger phrase)
**Required for Claude API; not needed for Bedrock/Vertex

### Common claude_args

```yaml
claude_args: |
  --max-turns 10
  --model claude-sonnet-4-5-20250929
  --append-system-prompt "Follow our coding standards"
  --allowed-tools Bash,Read,Write,Edit
  --mcp-config /path/to/config.json
```

**Available arguments:**
- `--max-turns N` — Maximum conversation turns (default: 10)
- `--model MODEL` — Model to use (sonnet, opus, haiku, or full ID)
- `--append-system-prompt TEXT` — Add custom instructions
- `--allowed-tools LIST` — Comma-separated tool allowlist
- `--disallowed-tools LIST` — Comma-separated tool denylist
- `--mcp-config PATH` — MCP server configuration
- `--debug` — Enable debug output

## Cloud Provider Setup

### AWS Bedrock

**Prerequisites:**
1. AWS account with Bedrock enabled
2. GitHub OIDC Identity Provider configured in AWS
3. IAM role with `AmazonBedrockFullAccess`

**Secrets needed:**
- `AWS_ROLE_TO_ASSUME` — IAM role ARN
- `APP_ID` — GitHub App ID (if using custom app)
- `APP_PRIVATE_KEY` — GitHub App private key (if using custom app)

**Workflow:**

```yaml
name: Claude with Bedrock
permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write

on:
  issue_comment:
    types: [created]

jobs:
  claude:
    runs-on: ubuntu-latest
    env:
      AWS_REGION: us-west-2
    steps:
      - uses: actions/checkout@v4

      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Configure AWS Credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
          aws-region: us-west-2

      - uses: anthropics/claude-code-action@v1
        with:
          github_token: ${{ steps.app-token.outputs.token }}
          use_bedrock: "true"
          claude_args: '--model us.anthropic.claude-sonnet-4-5-20250929-v1:0 --max-turns 10'
```

### Google Vertex AI

**Prerequisites:**
1. GCP project with Vertex AI API enabled
2. Workload Identity Federation configured
3. Service account with Vertex AI User role

**Secrets needed:**
- `GCP_WORKLOAD_IDENTITY_PROVIDER` — Workload identity provider resource name
- `GCP_SERVICE_ACCOUNT` — Service account email
- `APP_ID` — GitHub App ID (if using custom app)
- `APP_PRIVATE_KEY` — GitHub App private key (if using custom app)

**Workflow:**

```yaml
name: Claude with Vertex AI
permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write

on:
  issue_comment:
    types: [created]

jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Authenticate to Google Cloud
        id: auth
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
          service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}

      - uses: anthropics/claude-code-action@v1
        with:
          github_token: ${{ steps.app-token.outputs.token }}
          use_vertex: "true"
          claude_args: '--model claude-sonnet-4@20250514 --max-turns 10'
        env:
          ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
          CLOUD_ML_REGION: us-east5
          VERTEX_REGION_CLAUDE_3_7_SONNET: us-east5
```

## Best Practices

### 1. Use CLAUDE.md for Project Guidelines

Create `CLAUDE.md` at repository root to define:
- Code style guidelines
- Review criteria
- Project-specific rules
- Preferred patterns

Claude will follow these guidelines automatically.

### 2. Security

- ✅ **DO**: Use GitHub Secrets for API keys
- ✅ **DO**: Limit action permissions to minimum required
- ✅ **DO**: Review Claude's suggestions before merging
- ❌ **DON'T**: Commit API keys to repository
- ❌ **DON'T**: Use overly permissive permissions

### 3. Cost Optimization

**GitHub Actions costs:**
- Runs on GitHub-hosted runners (consumes Actions minutes)
- See [GitHub billing docs](https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions)

**API costs:**
- Consumes tokens based on prompt/response length
- Varies by task complexity and codebase size

**Optimization tips:**
- Use specific `@claude` commands
- Set appropriate `--max-turns` in `claude_args`
- Configure workflow-level timeouts
- Use concurrency controls to limit parallel runs

### 4. Performance Optimization

- Use issue templates to provide context
- Keep `CLAUDE.md` concise and focused
- Configure appropriate timeouts
- Use specific commands vs. open-ended prompts

## Troubleshooting

### Claude not responding to @claude

**Check:**
- GitHub App is installed correctly
- Workflows are enabled in repository settings
- API key is set in repository secrets
- Comment contains `@claude` (not `/claude`)
- Workflow file has correct event triggers

### Authentication errors

**For Claude API:**
- Verify `ANTHROPIC_API_KEY` is valid
- Check API key has sufficient permissions
- Ensure secret name matches workflow reference

**For Bedrock:**
- Verify IAM role ARN is correct
- Check Bedrock access is enabled
- Ensure OIDC provider is configured
- Verify trust policy allows GitHub Actions

**For Vertex AI:**
- Verify workload identity provider resource name
- Check service account has Vertex AI permissions
- Ensure project ID is correct
- Verify API is enabled in GCP project

### CI not running on Claude's commits

**Solution:**
- Use GitHub App or custom app (not GITHUB_TOKEN)
- Verify app permissions include CI triggers
- Check workflow triggers include necessary events

### Workflow runs but Claude doesn't act

**Check:**
- `prompt` is provided OR trigger phrase detected
- Permissions are sufficient (contents: write, etc.)
- Workflow completed without errors (check logs)
- Rate limits not exceeded

## Upgrading from Beta to v1.0

### Breaking Changes

**Action version:**
```yaml
# Before
uses: anthropics/claude-code-action@beta

# After
uses: anthropics/claude-code-action@v1
```

**Parameters changed:**

| Beta Input            | v1.0 Input                        |
|-----------------------|-----------------------------------|
| `mode`                | *(Removed - auto-detected)*       |
| `direct_prompt`       | `prompt`                          |
| `override_prompt`     | `prompt` with GitHub variables    |
| `custom_instructions` | `claude_args: --append-system-prompt` |
| `max_turns`           | `claude_args: --max-turns`        |
| `model`               | `claude_args: --model`            |
| `allowed_tools`       | `claude_args: --allowedTools`     |
| `disallowed_tools`    | `claude_args: --disallowedTools`  |

**Migration example:**

```yaml
# Beta
- uses: anthropics/claude-code-action@beta
  with:
    mode: "tag"
    direct_prompt: "Review for security"
    custom_instructions: "Follow standards"
    max_turns: "10"

# v1.0
- uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review for security"
    claude_args: |
      --append-system-prompt "Follow standards"
      --max-turns 10
```

## Examples Repository

Find more examples at: https://github.com/anthropics/claude-code-action/tree/main/examples

## When to Use This Skill

Use `/github-actions` when you need to:
- Set up Claude Code GitHub Actions for the first time
- Create or modify workflow files
- Configure AWS Bedrock or Google Vertex AI integration
- Troubleshoot authentication or permission issues
- Optimize performance or costs
- Upgrade from beta to v1.0
- Understand action parameters and configuration options

## User Task

Help the user with their GitHub Actions setup or configuration question.
