cicaddy-gitlab 0.4.0

GitLab platform plugin for cicaddy AI agent

cicaddy-gitlab

GitLab platform plugin for the cicaddy AI agent framework.

Features

• Merge Request Code Review - AI-powered code review on GitLab merge requests with inline comments
• Sub-Agent Delegation - AI-powered multi-agent review with specialized sub-agents running in parallel
• Branch Review - Compare branch changes against main for deployment readiness analysis
• Scheduled Analysis - Cron-based AI analysis jobs with MCP tool integration
• Multi-Provider AI - Support for Gemini, OpenAI, Claude, Anthropic via Vertex AI
• DSPy Task Files - Declarative YAML prompt definitions for structured analysis
• GitLab CI Templates - Ready-to-use CI/CD templates for merge request and scheduled jobs

Installation

pip install cicaddy-gitlab

This automatically installs cicaddy core as a dependency and registers the GitLab plugin via entry points.

Prerequisites

Set up your AI provider API key as a GitLab CI/CD variable before adding the templates.

Using Gemini as an example:

1. Go to Settings > CI/CD > Variables in your GitLab project
2. Click Add variable
3. Set Key to GEMINI_API_KEY, paste your API key as Value
4. Check Mask variable, then click Add variable

See docs/getting-started.md for other providers (OpenAI, Claude, Anthropic Vertex AI) and full security best practices.

Quick Start

Merge Request Code Review

Add to your .gitlab-ci.yml:

include:
  - remote: 'https://raw.githubusercontent.com/redhat-community-ai-tools/cicaddy-gitlab/main/gitlab/ai_agent_template.yml'

ai_code_review:
  extends: .ai_agent_template
  variables:
    AI_PROVIDER: "gemini"
    GEMINI_API_KEY: $GEMINI_API_KEY
    DELEGATION_MODE: "auto"
    SLACK_WEBHOOK_URL: $SLACK_WEBHOOK_URL

Sub-Agent Delegation: When DELEGATION_MODE is set to auto, the agent uses AI-powered triage to analyze the MR diff and spawns specialized sub-agents in parallel (e.g., code quality, security, performance). Each sub-agent runs with a focused scope and reduced token budget, and their results are aggregated into a single unified review. This produces deeper, more structured reviews compared to single-agent mode. Set DELEGATION_MODE: "none" to use a single agent instead. See docs/delegation.md for details.

Scheduled Analysis with MCP Tools

include:
  - remote: 'https://raw.githubusercontent.com/redhat-community-ai-tools/cicaddy-gitlab/main/gitlab/ai_cron_template.yml'

daily_analysis:
  extends: .ai_cron_template
  variables:
    AI_PROVIDER: "gemini"
    GEMINI_API_KEY: $GEMINI_API_KEY
    MCP_SERVERS_CONFIG: >-
      [{"name": "my-server", "protocol": "http",
        "endpoint": "https://my-mcp-server.example.com/mcp",
        "timeout": 300, "idle_timeout": 60}]
    AI_TASK_PROMPT: |
      Use MCP tools to analyze data and generate a comprehensive report.
    SLACK_WEBHOOK_URL: $SLACK_WEBHOOK_URL
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"

Using DSPy Task Files

Create structured task definitions in YAML:

# .gitlab/prompts/my_analysis.yml
name: custom_analysis
description: Custom analysis task
type: analysis
version: "1.0"

inputs:
  - name: data_source
    description: Data source to analyze
    required: true

outputs:
  - name: summary
    description: Analysis summary
    required: true
    format: paragraph

constraints:
  - Focus on actionable insights
  - Prioritize by business impact

reasoning: chain_of_thought
output_format: markdown

Reference it in your CI job:

custom_analysis:
  extends: .ai_cron_template
  variables:
    AI_TASK_FILE: "../.gitlab/prompts/my_analysis.yml"

CI Template Variables

Common Variables

Variable	Default	Description
AI_PROVIDER	gemini	AI provider (gemini, openai, claude, anthropic-vertex)
AI_MODEL	gemini-3-flash-preview	Model to use
MCP_SERVERS_CONFIG	[]	JSON array of MCP server configs
AI_TASK_FILE	(empty)	Path to DSPy task YAML file
AI_TASK_PROMPT	(built-in)	Inline task prompt
SLACK_WEBHOOK_URL	(empty)	Slack webhook for notifications
MAX_INFER_ITERS	15	Max AI inference iterations (agent: 15, cron: 30)
DELEGATION_MODE	none	none (single-agent) or auto (multi-agent delegation)
MAX_SUB_AGENTS	3	Maximum concurrent sub-agents (1-10)
SUB_AGENT_MAX_ITERS	10	Max inference iterations per sub-agent (1-15)
DELEGATION_AGENTS_DIR	.agents/delegation	Custom agent YAML directory
DELEGATION_AGENTS	(empty)	JSON config for inline custom sub-agents
TRIAGE_PROMPT	(empty)	Custom triage instructions
LOG_LEVEL	INFO	Logging verbosity

Agent Template Variables

Variable	Default	Description
AGENT_TASKS	code_review	Comma-separated task list
DELEGATION_MODE	none	auto for AI-powered sub-agent delegation, none for single-agent
MAX_SUB_AGENTS	3	Max concurrent sub-agents (1-10)
SUB_AGENT_MAX_ITERS	5	Max iterations per sub-agent (1-15)
GIT_DIFF_CONTEXT_LINES	10	Context lines in diff
GIT_WORKING_DIRECTORY	.	Git repo directory

Cron Template Variables

Variable	Default	Description
TASK_TYPE	custom	Prompt template: custom (uses AI_TASK_PROMPT/AI_TASK_FILE), security_audit, quality_report, dependency_check; other values use general analysis
TASK_SCOPE	external_tools	Analysis scope
MAX_EXECUTION_TIME	600	Max execution time (seconds)
CONTEXT_SAFETY_FACTOR	0.75	Token budget safety factor

Architecture

cicaddy (core)          - AI agent framework with MCP support
  +-- cicaddy-gitlab    - GitLab platform plugin (this package)

The plugin registers with cicaddy via Python entry points:

• cicaddy.agents - MergeRequestAgent, BranchReviewAgent
• cicaddy.settings_loader - GitLab-specific settings
• cicaddy.cli_args - GitLab CLI arguments
• cicaddy.validators - GitLab configuration validation
• cicaddy.delegation_blocked_tools - Side-effect tools blocked for sub-agents

Running Locally

You can run the agent outside of GitLab CI for development and testing using .env files.

# Install from source
git clone https://github.com/redhat-community-ai-tools/cicaddy-gitlab.git
cd cicaddy-gitlab
uv pip install -e .

# Prepare environment file
cp .env.example .env.local
# Edit .env.local with your API key and settings

# Validate configuration
uv run cicaddy config show --env-file .env.local

# Run the agent
uv run cicaddy run --env-file .env.local

# Override settings via CLI
uv run cicaddy run --env-file .env.local --ai-provider openai --verbose

For MR review, use .env.mr.example as a starting point — it includes GitLab API variables (GITLAB_TOKEN, CI_MERGE_REQUEST_IID, etc.).

See docs/running-locally.md for detailed examples including MCP server configuration, DSPy task files, and troubleshooting.

Development

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Lint and format
ruff check --fix src/ tests/
ruff format src/ tests/

License

Apache License 2.0