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

Clone this repository into your GitLab project.

Install dependencies (for local development or debugging):

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

Configuration

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
Edit
```
.claude-gitlab.yml
```
(recommended model:
```
claude-opus-4-20250514
```
):
Customize model, allowed tools, and prompts as needed.
(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:

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

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

Copy the
orchestrator/
directory and
.gitlab-ci.yml
into your own GitLab project.
Set up the required environment variables in your project's CI/CD settings (see above).
(Optional) Deploy the webhook handler if you want comment-triggered reviews.
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.

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

Clone this repository into your GitLab project.

Install dependencies (for local development or debugging):

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

Configuration

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
Edit
```
.claude-gitlab.yml
```
(recommended model:
```
claude-opus-4-20250514
```
):
Customize model, allowed tools, and prompts as needed.
(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:

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

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

Copy the
orchestrator/
directory and
.gitlab-ci.yml
into your own GitLab project.
Set up the required environment variables in your project's CI/CD settings (see above).
(Optional) Deploy the webhook handler if you want comment-triggered reviews.
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.

Claude Code for GitLab CI/CD

Related Skills

<h1 align="center">

- Identify gaps

2. Apply Deepthink Protocol (reason about dependencies