Claude Code for GitLab CI/CD

1. Project Overview

This project leverages Anthropic's Claude Code product in GitLab CI pipelines, providing access to powerful AI tools in your build pipeline.

Key Features and Value Proposition

• AI-Powered Code Reviews (review_merge_request job): Analyzes merge request diffs and posts line-specific feedback as GitLab discussions, covering bugs, security, performance, and code quality. Triggered automatically on MR events or by commenting @claude-code review.

• Conversational Code Assistant (claude_comment_response job): Responds to any @claude-code mention in MR comments with contextual help, code explanations, and targeted suggestions. Can investigate your codebase and provide detailed answers about specific files or functions.

• Code Modification on Request: When asked via comments, Claude can read your code, implement requested changes, and push commits directly to your branch with clear attribution and descriptive commit messages.

Recent Improvements (2025)

• CLI-Based Architecture: Migrated from Python SDK to Claude CLI for maximum reliability and robust JSON parsing in CI/CD environments
• Test Suite Performance: Comprehensive test suite now runs in ~0.5 seconds (previously 25+ seconds) with 87%+ coverage
• Enhanced Webhook Reliability: Improved webhook handler with rate limiting, bot detection, and comprehensive diagnostic tools
• On-Demand Reviews: Switched to comment-triggered reviews (@claude-code review) to reduce noise and cost

---

2. Quick Start: Setup, Configuration, and Usage

Prerequisites

• GitLab project with CI/CD enabled
• Anthropic Claude API key (or Claude Code CLI installed)
• GitLab bot user and tokens for commenting and pushing changes
• Python 3.8+ and Docker (for local development or CI runners)

Installation

1. Clone this repository into your GitLab project.

2. Install dependencies (for local development or debugging):

   pip install -r requirements.txt
   pip install -r requirements-test.txt  # For running tests
   

Configuration

1. Set up environment variables in your GitLab project under Settings > CI/CD > Variables:

   • ANTHROPIC_API_KEY: Your Claude API key
   • CLAUDE_BOT_USERNAME: The username of your GitLab bot user (e.g., claude-bot)
   • CLAUDE_COMMENTER_TOKEN: Project Access Token for commenting and pushing changes
   • GITLAB_AUTOFIX_TOKEN: Project Access Token for auto-fix pushes

2. Edit .claude-gitlab.yml (recommended model: claude-opus-4-20250514):
   Customize model, allowed tools, and prompts as needed.

3. (Optional) Edit settings.json:
   Fine-tune tool permissions and ignore patterns.

How to Run

• In CI/CD:
  The orchestrator runs automatically in your GitLab pipeline for merge requests and build failures.
• Manually (for debugging):

  python -m orchestrator --review-mode
  python -m orchestrator --fix-failure
  python -m orchestrator --comment-mode
  

Webhook Service Setup (GCP Example)

The webhook handler includes comprehensive diagnostic tools for easy troubleshooting:

1. Deploy and diagnose:

   cd webhook-handler
   ./deploy-to-gcp.sh           # Deploy to Google Cloud Run
   ./diagnose_webhook.py        # Full health check
   ./verify_gcp_secrets.sh      # Validate secret configuration
   

2. Test and debug:

   ./run_pipeline_trigger.py    # Test triggers directly
   ./test_webhook_locally.py    # Test webhook handler locally
   

See webhook-handler/CLAUDE.md for complete diagnostic workflow.

First-Time User Checklist

• Clone the repo and install dependencies
• Set up all required environment variables in GitLab CI/CD
• (Optional) Customize .claude-gitlab.yml and settings.json
• Deploy the webhook handler (if using comment triggers)
• Open a merge request and mention @claude-code to trigger a review or code change

How to Use This in Your Own Project

1. Copy the orchestrator/ directory and .gitlab-ci.yml into your own GitLab project.
2. Set up the required environment variables in your project's CI/CD settings (see above).
3. (Optional) Deploy the webhook handler if you want comment-triggered reviews.
4. Open a merge request and mention @claude-code to trigger a review or code change.

For a minimal working example, follow the checklist above or see the documentation for more details.

---

3. How It Works

High-Level Workflow

• Trigger:
  • The system is activated by GitLab CI events (e.g., merge request opened, build failure) or by mentioning @claude-code in a merge request comment.
• Review:
  • Claude analyzes the merge request diff and provides actionable, line-specific feedback as a comment in the MR.
• Auto-fix:
  • On build/test failure, Claude reviews the error logs, diagnoses the problem, and can suggest or apply code fixes automatically.
• Comment Response:
  • When @claude-code is mentioned in an MR comment, Claude can answer questions, review code, or even push code changes in response.

Supported Modes

• Review Mode:
  Automated code review for merge requests.
• Auto-fix Mode:
  Automated diagnosis and fixing of build/test failures.
• Comment Mode:
  Responds to MR comments and can make code changes on request.

How Claude is Invoked

• CLI-First Approach:
  All AI operations use the Claude Code CLI (not the Python SDK) for maximum reliability and robust JSON output.
  • Avoids streaming/multiline parsing issues present in Python SDK
  • Ensures stable operation in CI/CD environments
  • Includes automatic retry logic with exponential backoff for rate limiting
  • Uses minimal environment passing to prevent "Argument list too long" errors

How to Trigger Reviews and Fixes

• Merge Request Review:
  • Open a merge request or push new commits.
  • Or, comment @claude-code review on the MR to trigger an on-demand review.
• Auto-fix:
  • When a CI job fails, the orchestrator automatically invokes Claude to analyze and fix the failure.
• Comment Response:
  • Mention @claude-code in any MR comment to ask a question, request a change, or get help.

---

4. Modular Architecture

This project is built around a modular orchestrator package and a dedicated webhook handler, enabling robust, maintainable, and extensible AI-powered automation in GitLab CI/CD.

Orchestrator Package

• Purpose:
  The orchestrator is the core engine that manages all AI-driven automation, including code reviews, auto-fixes, and comment responses.

• Key Modules:

  • main.py / cli.py: Entry points and command-line interface.
  • config_manager.py: Loads and merges configuration from YAML, JSON, and environment variables.
  • gitlab_client.py: Handles all GitLab API interactions (MRs, comments, CI jobs).
  • claude_sdk_client.py: Invokes the Claude Code CLI for all AI operations (not the Python SDK).
  • comment_handler.py: Processes @claude-code mentions and formats context for Claude.
  • git_operations.py: Handles git diffs, commits, and pushes as needed.
  • logger.py, exceptions.py, utils.py: Logging, error handling, and shared utilities.

• Design Principles:

  • Each module has a single, well-defined responsibility.
  • Layered configuration and robust error handling.
  • Structured logging and testability throughout.

Legacy Compatibility

• The orchestrator maintains backward compatibility with the original orchestrator.py script.
• All new features and workflows are implemented in the modular package, with the legacy script acting as a thin wrapper.

Webhook Handler

• Purpose:
  A separate service (typically deployed on Google Cloud Run) that listens for GitLab MR comment webhooks.
• Role:
  Triggers the orchestrator in response to @claude-code mentions, enabling real-time, comment-driven automation.
• Deployment:
  Can be run on GCP or any platform that supports Python and webhooks.

Test Suite and TDD Requirements

⚠️ Test-Driven Development (TDD) is MANDATORY

• Write failing tests FIRST before any implementation
• All features must follow RED → GREEN → REFACTOR cycle
• Run tests with: python3 -m pytest (runs in ~0.5 seconds)
• Coverage requirement: 87%+ on core components
• All modules are covered by unit and integration tests (see tests/CLAUDE.md for details)

---

5. Quick Troubleshooting

Webhook Issues:

cd webhook-handler
./diagnose_webhook.py        # Comprehensive health check
./run_pipeline_trigger.py    # Test pipeline triggers directly
./verify_gcp_secrets.sh      # Check Google Secret Manager

Common Issues:

• Webhook disabled by GitLab → Use ./run_pipeline_trigger.py as workaround
• Rate limiting → Built-in exponential backoff with 5 retries
• Environment variables → Run diagnostic script to validate

See WEBHOOK_TROUBLESHOOTING.md for detailed solutions.

---

6. References and Further Reading

• Project-wide and Workflow Documentation:
  See CLAUDE.md in the project root for context management, workflow, and best practices.

• Orchestrator Module Details:
  See orchestrator/CLAUDE.md for a deep dive into the modular architecture, configuration, and error handling.

• Test Suite and TDD Practices:
  See tests/CLAUDE.md for details on test-driven development, test coverage, and testing patterns.

• Webhook Handler Documentation:
  See webhook-handler/CLAUDE.md for information on the webhook service, deployment, and troubleshooting.

• Additional Technical Docs:

  • docs/architecture.md: High-level system architecture
  • docs/features.md: Feature overview
  • docs/ci-setup.md: CI/CD setup and configuration
  • docs/troubleshooting.md: Troubleshooting common issues
  • docs/webhook-architecture.md: Webhook design and flow

• Taskmaster Integration:
  This project uses Taskmaster AI for task management and planning.