MigrateIQ

Inspiration

Every developer has experienced the pain of framework migrations — updating React class components to hooks, replacing deprecated libraries like moment.js, or upgrading Express.js versions. These tasks are tedious, error-prone, and can take weeks for large codebases.

Existing tools like Renovate and Dependabot only bump version numbers in manifest files. They cannot rewrite actual source code when APIs change. Google Research published findings showing that code migration is one of their most significant engineering maintenance costs, even with world-class tooling. The EU Cyber Resilience Act (2026) adds regulatory pressure to keep dependencies updated. AI-generated code often uses outdated patterns, accelerating technical debt.

I built MigrateIQ to fill this gap — an intelligent migration assistant that doesn't just detect outdated code, it actually rewrites it file-by-file, preserving business logic and creating a ready-to-review merge request.

What it does

MigrateIQ is a 5-agent flow on the GitLab Duo Agent Platform that automates the entire code migration lifecycle:

MCP Data Fetcher — Dynamically reads the project's package.json (no hardcoded paths), then executes 4 curl commands via run_command to fetch real-time intelligence from an MCP server deployed on Google Cloud Run. Sends the real dependencies to /analyze-project for version + CVE analysis via deps.dev and OSV.dev, researches the most critical package migration via Vertex AI Gemini with Grounding with Google Search (/vertex/research-migration), fetches step-by-step migration recipes from the BigQuery pattern database, and uploads a pre-migration report to Google Cloud Storage. Total: 5 run_command calls (1 cat + 4 curl).
Dependency Scanner Agent — Dynamically discovers source files using find_files (patterns: *.js, *.jsx, *.ts, *.tsx) and scans for migration patterns using grep. Uses the real vulnerability and version data from the Fetcher (not LLM knowledge). Only searches for patterns relevant to the project's actual dependencies. Posts a comprehensive Migration Health Report on the issue with real GHSA IDs, severity categorization, and affected files per pattern.
Migration Planner Agent — Reads each discovered file to assess complexity. Creates a file-by-file migration plan with dependency-aware execution order (utilities → tests → server → components → package.json). Incorporates Google Search grounded research data from the Fetcher for breaking changes awareness. Posts the plan as an issue comment with complexity per file, phase rationale, and branch strategy.
Code Migrator Agent — Reads each source file from the repository and rewrites it applying migration recipes and Google Search grounded research data. Creates one atomic commit per file on a new branch (migrateiq/full-migration) — commit count matches the number of files in the plan. Handles: React class→hooks, CommonJS→ESM, moment→native Intl, Express 4→5, lodash→native, axios 0.x→1.x. Preserves comments, business logic, and data-testid attributes.
Migration Validator Agent — Archives a completion report to Google Cloud Storage. Creates a comprehensive Merge Request with per-file changelog, testing checklist, rollback instructions, and deployment requirements. Posts a validation report on the MR. Links back to the original issue with completion status and next steps.

The flow is triggered by mentioning or assigning the MigrateIQ service account on a GitLab issue.

Supported migrations:

React 17 class components → React 19 functional components with hooks
CommonJS require()/module.exports → ES Module import/export
moment.js (deprecated) → Native Intl.DateTimeFormat / Intl.RelativeTimeFormat
Express 4 body-parser → Express 5 express.json()
lodash full import → Native Array methods (filter, sort)
axios 0.x → axios 1.x (full code rewrite: CancelToken→AbortController, interceptor types, error handling)

7 Google Cloud services integrated (all returning real data):

Google deps.dev — Real-time package version lookups and license information
Google OSV.dev — Real-time vulnerability scanning with actual GHSA/CVE IDs
Google Vertex AI Gemini (gemini-2.5-flash) — AI-powered code analysis, migration risk scoring, complexity assessment
Grounding with Google Search — Live web research via Gemini for latest migration guides, breaking changes, and official docs
Google BigQuery — Migration pattern database with step-by-step recipes, success rates, and edge cases
Google Cloud Storage — Migration report archival with artifact management
Google Cloud Run — Hosts the MCP Intelligence Hub server (auto-scaling, serverless)

How we built it

GitLab Duo Agent Platform:

5 custom agents with specialized system prompts, each with strict safety guards (NEVER RETRY rules, max tool call limits, numbered call tracking)
1 custom flow (YAML) orchestrating all 5 agents sequentially using context:agent.final_answer for data passing
Triggers configured for mention and assign events on GitLab issues
AGENTS.md providing project context to all agents (tech stack, migration targets, code style rules)
.migrateiq.yml configuration file for customizable migration rules, exclusion paths, and settings
.gitlab/duo/agent-config.yml with network policy to allow outbound HTTPS to the Cloud Run MCP server and setup script to install curl in the CI/CD runner

Agent tools used: run_command, list_repository_tree, get_repository_file, read_file, find_files, grep, create_commit, create_merge_request, create_merge_request_note, create_issue_note, get_issue (11 tools)

MCP Intelligence Hub (Node.js on Cloud Run):

14 HTTP endpoints integrating 7 Google Cloud services
/analyze-project — Dynamic analysis accepting raw package.json content (deps.dev + OSV.dev)
/analyze — Combined deps.dev + OSV.dev dependency health analysis (accepts dependency map)
/vertex/analyze-code and /vertex/suggest-migration — Vertex AI Gemini integration
/vertex/research-migration — Vertex AI Gemini + Google Search grounding for live migration research
/recipe/{type} — Step-by-step migration recipes from BigQuery pattern database
/storage/upload-report and /storage/reports/{project} — Cloud Storage artifact management
Plus /dependency, /version, /vulnerabilities, /patterns, /search, /tools endpoints

Demo repository: A task management application with intentionally outdated code — React 17 class components (3 files, 476+ lines), Express 4 server with body-parser and moment.js, CommonJS modules, lodash full imports, and a Jest test suite.

Challenges we ran into

SRT Network Sandbox blocking MCP server calls — GitLab CI/CD flows use Anthropic Sandbox Runtime (SRT) which blocks ALL outbound network traffic except to the GitLab instance by default. Our curl commands to the Cloud Run MCP server were silently blocked, returning empty responses. We solved this by creating .gitlab/duo/agent-config.yml with network_policy.allowed_domains to whitelist the MCP server domain and a setup_script to install curl.
Agent infinite loop from missing retry guards — The fetcher agent's prompt said "call run_command 7 times" but didn't say "NEVER RETRY". When curl returned empty (due to the network sandbox), the agent retried the same command infinitely. We added explicit "NEVER RETRY" rules with numbered call tracking ("call 1 of 7") to every agent prompt.
Project ID resolution in ambient flows — Tools like create_commit and create_issue_note failed because agents couldn't resolve the project ID in the flow execution context. We solved this by passing context:project_id as an explicit input to every agent component.
Balancing output quality vs safety — Strict character limits and rigid templates prevented infinite loops but produced minimal output. We iteratively relaxed output constraints while keeping all safety guards, achieving rich production-quality reports without risking agent runaway.
Context passing between agents — Ensuring the scanner's findings were structured enough for the planner, and the planner's output was actionable for the migrator. We used structured text blocks with clear delimiters in final_answer for reliable agent-to-agent communication.

Accomplishments that we're proud of

Full end-to-end flow working in production — 5 agents execute sequentially in ~8 minutes, triggered by a single @mention on an issue
All 7 Google Cloud services return real data — not mock data, not LLM hallucinations. Real GHSA IDs from OSV.dev, real package versions from deps.dev, real research from Vertex AI Gemini with Google Search grounding (with citations)
Atomic commits with properly migrated code (one per file) on a dedicated branch, with pipeline passing
Rich MR description with per-file changelog, testing checklist, rollback instructions, and deployment requirements
Comprehensive issue comments — Health Report with CVE details and severity, Migration Plan with risk score and execution rationale, completion summary with next steps
Validation report posted on the MR with migration metrics, testing steps, and deployment requirements
MCP Intelligence Hub with 14 endpoints integrating 7 GCP services, deployed on Cloud Run
Configuration-driven — .migrateiq.yml lets teams customize which migrations to enable, exclusion paths, and settings

What we learned

The GitLab Duo Agent Platform is powerful for multi-agent orchestration, but CI/CD flow execution uses SRT network sandboxing that requires explicit domain whitelisting
Prompt engineering for multi-agent flows requires strict safety guards — explicit "NEVER RETRY" rules, numbered tool call tracking, and max call limits prevent agent runaway
Agent-to-agent communication via final_answer works well when output uses clear section delimiters
The flow YAML schema (v1) with components, prompts, routers, and entry_point provides clean orchestration with context passing
Real-world code migration requires careful prompt design to preserve business logic while transforming patterns
Network policy configuration (.gitlab/duo/agent-config.yml) is essential for any flow that calls external services

What's next for MigrateIQ

Support additional languages: Python (2→3 patterns), Java (Spring Boot 2→3), TypeScript strict mode
Integration with GitLab's native vulnerability scanning to prioritize security-critical migrations
Self-evolving pattern learning: store successful migration patterns back to BigQuery and improve accuracy over time
Support for monorepo migrations (multiple packages in a single repository)
Automated test generation for migrated code to verify behavioral equivalence
Organization-wide migration campaigns across multiple repositories