AI Code Review Workflow

An automated GitHub Actions workflow that provides comprehensive AI-powered code reviews for pull requests. This workflow analyzes code quality, documentation, security, and provides actionable feedback to developers.

Overview

The AI Code Review workflow automatically triggers on pull request events and provides:

Comprehensive code quality assessment
Documentation review and suggestions
Security analysis
Performance considerations
Actionable improvement recommendations

Features

Automatic Triggers: Runs on PR open, synchronize, and reopen events
Comprehensive Analysis: Multi-faceted code review covering quality, security, and documentation
Professional Format: Structured, actionable feedback in standard code review format
Summary Comments: Additional summary comment for easy tracking
Error Resilience: Continues execution even if individual steps fail

Configuration

Required Secrets

APP_ID: GitHub App ID for token generation
PRIVATE_KEY: GitHub App private key
CLAUDE_CODE_OAUTH_TOKEN: OAuth token for Claude Code integration

Permissions

The workflow requires the following permissions:

contents: read - Read repository content and changes
pull-requests: write - Comment on pull requests
issues: write - Comment on issues (if needed)

Usage

The workflow automatically runs on pull request events. No manual intervention is required once configured.

Supported Events

pull_request.opened - New pull requests
pull_request.synchronize - Updates to existing pull requests
pull_request.reopened - Reopened pull requests

Review Criteria

The AI reviewer analyzes pull requests across multiple dimensions:

🔍 Code Quality Assessment

Overall Rating: Numerical quality score (1-10)
Maintainability: Code structure and organization
Readability: Code clarity and naming conventions
Best Practices: Adherence to language and framework standards
Performance: Potential performance impacts and optimizations

📚 Documentation Review

Comment Quality: Inline code comments and documentation
Function Documentation: Method and function documentation completeness
README Updates: Checks if README updates are needed for new features
API Documentation: Interface and API documentation quality

🎯 Specific Recommendations

Actionable Improvements: Specific, prioritized suggestions
Refactoring Opportunities: Code structure improvements
Testing Recommendations: Test coverage and quality suggestions
Security Considerations: Potential security issues or improvements

Implementation Details

Event Triggers

on:
  pull_request:
    types: [opened, synchronize, reopened]

Analysis Process

Code Checkout: Full repository history for comprehensive context
Authentication: GitHub App token generation for API access
AI Analysis: Claude Code performs detailed code review
Summary Generation: Posts additional summary comment

Review Prompt

The workflow uses a structured prompt to ensure consistent, comprehensive reviews:

direct_prompt: |
  You are the AI code quality reviewer for our organization.

  Please analyze this pull request for:

  ## 🔍 Code Quality Assessment
  - Overall code quality rating (1-10)
  - Code maintainability and readability
  - Adherence to best practices
  - Performance considerations

  ## 📚 Documentation Review
  - Comment quality and completeness
  - Function/method documentation
  - README updates if needed

  ## 🎯 Specific Recommendations
  - Actionable improvements with priorities
  - Code refactoring suggestions
  - Testing recommendations

  Format your response as a professional code review.

Workflow Steps

1. Code Checkout

- name: Checkout Code
  uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Get full history for better context

2. Authentication

- name: Generate Custom App Token
  id: generate-token
  uses: actions/create-github-app-token@v1
  with:
    app-id: ${{ secrets.APP_ID }}
    private-key: ${{ secrets.PRIVATE_KEY }}

3. AI Review

- name: AI Code Quality Review
  uses: anthropics/claude-code-action@v0
  continue-on-error: true
  timeout-minutes: 10

4. Summary Comment

- name: Post Summary Comment
  continue-on-error: true
  run: |
    gh pr comment ${{ github.event.number }} --body "
    ## 🤖 AI Code Review Complete
    [Summary content]
    "

Customization

Adjusting Review Criteria

Modify the direct_prompt to focus on specific aspects:

direct_prompt: |
  Focus on security analysis for this pull request:
  - Authentication and authorization
  - Input validation
  - Data encryption
  - Access controls

Changing Trigger Conditions

Add conditions to run only for specific cases:

on:
  pull_request:
    types: [opened, synchronize, reopened]
    paths:
      - 'src/**'
      - 'lib/**'

Custom Summary Messages

Modify the summary comment template:

- name: Post Summary Comment
  run: |
    gh pr comment ${{ github.event.number }} --body "
    ## 🔧 Custom Review Summary
    
    Your custom message here.
    
    Review checklist:
    - [ ] Code quality verified
    - [ ] Tests updated
    - [ ] Documentation current
    "

Integration with Development Process

Branch Protection Rules

Consider requiring AI review completion before merging:

# .github/branch-protection.yml
required_status_checks:
  - AI Code Review

Review Guidelines

Establish team guidelines for responding to AI feedback:

High Priority: Must be addressed before merging
Medium Priority: Should be addressed or documented
Low Priority: Consider for future improvements

Follow-up Actions

The workflow can trigger additional actions:

Automated testing for suggested changes
Documentation updates
Security scans for identified issues

Troubleshooting

Common Issues

Review not triggering
- Check workflow file location (.github/workflows/)
- Verify event types match your needs
- Ensure proper permissions are set
Authentication failures
- Verify GitHub App credentials
- Check Claude Code OAuth token
- Ensure app permissions include repository access
Timeout issues
- Adjust timeout-minutes for large PRs
- Consider splitting large changes
- Check Claude Code service limits

Quality Improvements

Monitor and improve review quality:

Collect feedback on review accuracy
Adjust prompts based on team needs
Track common issues for pattern recognition

This workflow provides automated, consistent code review coverage that helps maintain code quality standards while providing educational feedback to developers.