github-app-integration

Comprehensive guide to the Claude GitHub app, including installation, authentication, and cost structure.

Quick Answers

1. Is it free?

The GitHub app itself is free to install, but usage has costs:

• GitHub Actions minutes: Consumes your GitHub Actions quota (GitHub’s standard billing)
• Claude API usage: Requires either a Claude Pro/Max subscription OR API key with token credits

2. Does it work off Claude Code subscription or require API key?

Both options are available (as of Claude Code v1.0.44+):

Installation

Quick Setup (Recommended)

Using Claude Code CLI:

/install-github-app

This command:

1. Guides you through GitHub app installation
2. Configures required secrets automatically
3. Sets up OAuth token authentication (v1.0.44+)

Requirements:

• Repository admin access
• Claude Code installed locally
• Active Claude Pro/Max subscription OR Anthropic API key

Manual Installation

Step 1: Install the GitHub App Visit https://github.com/apps/claude and install to your repositories

Step 2: Configure Authentication Choose one of the following methods:

Option A: Subscription-Based (OAuth)

# Generate OAuth token
claude setup-token

# Add to GitHub Secrets as:
# CLAUDE_CODE_OAUTH_TOKEN

Option B: API Key

# Add to GitHub Secrets as:
# ANTHROPIC_API_KEY

Step 3: Add Workflow File Copy workflow example to .github/workflows/claude.yml from the claude-code-action repository

Authentication Methods

1. Subscription-Based OAuth (Recommended)

Introduced: Claude Code v1.0.44+

How it works:

• Uses your Claude Pro or Max subscription
• Authenticates via browser login (not API key)
• Generates OAuth token for GitHub Actions
• Shares rate limits with web/desktop Claude usage

Setup:

# In Claude Code terminal
/install-github-app

# Or manually:
claude setup-token
# Add CLAUDE_CODE_OAUTH_TOKEN to GitHub Secrets

Advantages:

• Predictable monthly cost
• No separate API billing
• Integrated with existing subscription
• Rate limits shared across all Claude interfaces

Rate Limits:

• Pro Plan: ~45 messages or 10-40 prompts per 5-hour window
• Max 5x Plan: ~225 messages or 50-200 prompts per 5-hour window
• Limits reset every 5 hours
• Shared with Claude web, desktop, and mobile usage

2. Direct API Key

How it works:

• Uses Anthropic API key from console.anthropic.com
• Pay-per-token consumption model
• No rate limit windows (usage-based billing)

Setup:

# Set environment variable
export ANTHROPIC_API_KEY="your-api-key"

# Or add to GitHub Secrets:
# ANTHROPIC_API_KEY

Advantages:

• No rate limit windows
• Suitable for high-volume usage
• More control over spending

Costs:

• Based on token consumption
• Varies by model (Sonnet, Opus, etc.)
• See https://www.anthropic.com/pricing for current rates

3. AWS Bedrock

How it works:

• Access Claude through AWS infrastructure
• Uses GitHub OIDC Identity Provider
• No static keys required

Setup: Requires AWS credential configuration with Bedrock access

4. Google Vertex AI

How it works:

• Access Claude through Google Cloud
• Uses Workload Identity Federation
• No static keys required

Setup: Requires Google Cloud credential configuration with Vertex AI access

Cost Structure

GitHub Actions Costs

Runner Minutes:

• Claude Code runs on GitHub-hosted runners
• Consumes your GitHub Actions minutes quota
• Standard GitHub Actions pricing applies

Free Tier:

• Public repositories: Unlimited minutes
• Private repositories: 2,000-50,000 minutes/month depending on plan

See: https://github.com/pricing for current GitHub Actions pricing

Claude Usage Costs

Subscription-Based (Pro/Max)

Pro Plan:

• **16.67/month billed annually at $200/year)
• ~45 messages or 10-40 prompts per 5-hour window
• Best for: Light coding tasks, repos under 1,000 lines
• Includes: Sonnet 4 model access
• No additional charges for GitHub integration

Max 5x Plan:

• $100/month
• ~225 messages or 50-200 prompts per 5-hour window
• Best for: Moderate usage, larger repositories
• Includes: Sonnet 4 and Opus 4 model access
• No additional charges for GitHub integration

Key Points:

• Rate limits reset every 5 hours
• Usage is shared across web, desktop, mobile, and Claude Code
• GitHub Actions count toward your usage quota
• No per-token charges when using subscription

API Key Usage

Pay-Per-Token:

• Charged based on input/output tokens
• Varies by model (Sonnet 4, Opus 4, etc.)
• No rate limit windows
• Direct consumption from API credits

Typical Costs:

• Each Claude interaction consumes tokens
• Cost depends on prompt/response length
• Task complexity affects token usage

See: https://www.anthropic.com/pricing for current API rates

Cost Optimization Strategies

1. Configure Appropriate Limits

# In workflow file
- uses: anthropics/claude-code-action@v1
  with:
    max-turns: 10  # Limit conversation length
    timeout-minutes: 15  # Prevent runaway executions

2. Use Specific Commands

• More specific prompts = fewer tokens
• Use targeted commands vs. broad questions
• Break complex tasks into smaller steps

3. Monitor Usage

# Check usage in Claude Code
/usage

# Check costs
/cost

4. Choose Right Plan

• Use subscription for predictable, moderate usage
• Use API key for high-volume or bursty workloads

GitHub App Capabilities

Features

Issue Management:

• Tag @claude in issues for implementation help
• Claude analyzes requirements and proposes solutions
• Can create branches and PRs directly

Pull Request Reviews:

• Respond to reviewer feedback automatically
• Fix CI errors identified in PR checks
• Modify code based on review comments

Code Modifications:

• Execute code changes from natural language
• Handle git workflows (branching, committing, pushing)
• Maintain code quality standards

Permissions Required

The GitHub app requires:

• Contents: Read & Write (to modify files)
• Issues: Read & Write (to comment and update)
• Pull Requests: Read & Write (to review and modify)

Workflow Integration

Example: Tag in Issue

Hey @claude, can you implement the feature described in this issue?
Follow our coding standards in CLAUDE.md.

Claude will:

1. Read issue description
2. Analyze codebase
3. Propose implementation
4. Create branch and PR
5. Add tests and documentation

Configuration

CLAUDE.md Files

Control Claude’s behavior through markdown configuration files:

Project-Level: .claude/CLAUDE.md

# Coding Standards

## Commit Messages
Follow conventional commit format:
- feat: New features
- fix: Bug fixes
- docs: Documentation changes

## Testing
Always include unit tests for new functionality.
Use our existing test patterns.

Global: ~/.claude/CLAUDE.md

# Personal Preferences

Always use TypeScript for new files.
Prefer functional components in React.

Workflow Customization

Example Workflow:

name: Claude Code

on:
  issues:
    types: [opened, labeled]
  issue_comment:
    types: [created]
  pull_request_review:
    types: [submitted]

jobs:
  claude:
    runs-on: ubuntu-latest

    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          claude-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          max-turns: 15
          timeout-minutes: 20

Comparison: Subscription vs API Key

Requirements Summary

GitHub Side:

• Repository admin access
• GitHub Actions enabled
• Required permissions (Contents, Issues, PRs)

Claude Side: Choose one:

• Option 1: Claude Pro or Max subscription ($20-100/month)
• Option 2: Anthropic API key with available credits
• Option 3: AWS Bedrock access
• Option 4: Google Vertex AI access

Local Setup:

• Claude Code CLI installed
• Authenticated with chosen method

Security Considerations

Credential Storage

• GitHub Secrets: Encrypted secret storage for tokens/keys
• macOS Keychain: Local credential encryption (desktop)
• Environment Variables: Custom credential scripts supported

Best Practices

1. Never commit tokens/keys to version control
2. Use GitHub Secrets for workflow authentication
3. Rotate tokens regularly (especially API keys)
4. Limit repository access to necessary repos only
5. Monitor usage for unexpected activity

Permissions Scope

• Grant minimum necessary permissions
• Review GitHub app permissions regularly
• Use repository-specific installations when possible

Troubleshooting

Authentication Issues

Problem: “Authentication failed”

# For subscription users:
claude setup-token
# Re-generate OAuth token and update GitHub Secret

# For API key users:
# Verify API key is valid at console.anthropic.com
# Check GitHub Secret is named correctly: ANTHROPIC_API_KEY

Problem: “Rate limit exceeded”

• Check current usage: /usage
• Wait for 5-hour reset window
• Consider upgrading from Pro to Max plan
• Or switch to API key for no rate limits

GitHub Actions Issues

Problem: “Runner timeout”

• Reduce max-turns limit in workflow
• Set appropriate timeout-minutes
• Use more specific prompts

Problem: “Permission denied”

• Verify repository admin access
• Check GitHub app permissions (Contents, Issues, PRs)
• Ensure GitHub Actions is enabled for repo

Cost Management

Problem: “Unexpected API charges”

• Monitor usage with /cost command
• Set workflow timeouts to prevent runaway costs
• Consider switching to subscription for predictability
• Use more specific prompts to reduce token usage

Migration Path

From API Key to Subscription

Advantages:

• Predictable monthly costs
• No per-token billing
• Integrated with Claude web/desktop

Steps:

1. Subscribe to Claude Pro or Max
2. Run /install-github-app in Claude Code
3. Generate OAuth token: claude setup-token
4. Replace ANTHROPIC_API_KEY secret with CLAUDE_CODE_OAUTH_TOKEN
5. Update workflow file if needed

From Subscription to API Key

Advantages:

• No rate limit windows
• Suitable for high-volume usage
• Independent from personal Claude usage

Steps:

1. Create API key at console.anthropic.com
2. Add as ANTHROPIC_API_KEY GitHub Secret
3. Remove CLAUDE_CODE_OAUTH_TOKEN secret
4. Update workflow to use API key
5. Monitor costs at Anthropic Console

Resources

Official Documentation:

• GitHub Actions Integration
• Authentication & IAM
• Security Considerations
• Setup Guide

GitHub Resources:

• Claude GitHub App
• claude-code-action Repository
• GitHub Actions Pricing

Pricing Information:

• Claude Code Plans
• Anthropic API Pricing
• Claude Pricing Overview

Community:

• Claude Code Issues
• Feature Requests

Last Updated: 2025-11-05 Claude Code Version: v1.0.44+ (OAuth Support) Information compiled from official Anthropic documentation and community resources