Migration Assistant

What is Migration Assistant?

Migration Assistant helps you migrate legacy CI/CD systems to GitHub Actions workflows. It ingests data from your existing CI/CD platform, walks you through a mapping wizard, and produces CodeCargo workspaces ready for AI-assisted conversion to GitHub Actions.

Currently supported source systems:

• Jenkins - Import jobs, pipelines, plugins, and credentials
• Azure DevOps - Import YAML pipelines, Classic Build/Release definitions, variable groups, service connections, and templates

The data model and UI are designed to be source-agnostic, making it straightforward to add support for additional CI/CD platforms in the future.

Source-Aware Terminology

Migration Assistant displays entity types using each source platform's native vocabulary while maintaining a stable internal data model. This ensures the interface feels natural regardless of your source CI/CD system.

This terminology layer applies across the overview landing, scoped entity tables, and mapping pages. When viewing data from multiple sources simultaneously, the interface falls back to neutral cross-platform terms for aggregate views while preserving source-specific labels in detailed breakdowns.

Getting Started

Access Migration Assistant from the organization sidebar under Migration Assistant. The main interface provides three ways to work with migrations:

Dashboard

The dashboard opens on an overview landing that groups all imported migration data by source system. Each source (Jenkins, Azure DevOps) displays its instances with progress indicators and summary metrics.

Instance Summary Cards

Each instance shows:

• Progress bar - segmented view of migrated, skipped, in-progress, and not-started jobs
• Completion percentage - jobs marked as migrated or intentionally skipped count toward completion
• Metric columns - aligned counts for build units, extensions, reusable code, and credentials
• Instance URL - normalized controller/organization URL for easy identification

Source-Scoped Navigation

Click any instance to drill down to a scoped entity table showing only that instance's data. The scoped view hides the source column (context is already established), shows the instance URL in the header, and uses that source's vocabulary throughout. Import is available from the overview level.

Within a scoped view you get statistics, filters, and inline editing capabilities:

• Summary statistics - jobs imported, mappings configured, repositories matched
• Filter controls - search by job name, filter by status or repository
• Inline mapping edits - update repository and migration mappings directly from the dashboard
• Per-job migration launch - trigger "Migrate in Editor" for individual jobs

Filtering

The dashboard supports multi-select Type and Status filters so you can focus on a specific subset of migration entities — for example, viewing only Jenkins Shared Libraries that are currently in progress.

Progress Bar

The segmented progress bar at the top of each instance or batch is interactive. Click any colored segment to filter the entity table to items in that state. Click the segment again, or click the legend label, to clear the filter.

Import Wizard

The import process follows a structured workflow:

1. Upload - Import data from your legacy CI/CD system
2. Review - Examine imported jobs, plugins, and credentials
3. Repository Mapping - Match legacy jobs to GitHub repositories
4. Reusable Building Blocks - Identify common patterns for reuse
5. Plugin & Credential Mappings - Map legacy plugins to GitHub Actions
6. Migration Mappings - Configure job-level migration settings
7. Confirm - Review summary and complete the import

The confirmation step shows at-a-glance summary cards with net changes, configured mappings, and jobs ready for migration.

Migrate

Launch individual job migrations into the GenAI Editor for AI-assisted conversion to GitHub Actions.

Jenkins Import

Migration Assistant includes a dedicated Jenkins importer that extracts comprehensive data from your Jenkins instance.

What Gets Imported

• Jobs and Pipelines - All job configurations and pipeline definitions
• Plugins - Installed plugins and their configurations
• Credentials - Credential definitions (values are not imported for security)
• Shared Libraries - Global pipeline libraries
• System Configuration - Relevant Jenkins system settings

Import Methods

JSON Upload

Upload a pre-exported JSON file containing your Jenkins data:

1. Navigate to Migration Assistant → Import → JSON
2. Upload your Jenkins export file
3. Follow the mapping wizard to configure your migration

Direct Jenkins Connection

Connect directly to your Jenkins instance for live data import:

1. Navigate to Migration Assistant → Import → Jenkins
2. Provide your Jenkins URL and authentication credentials
3. The importer will extract data directly from your Jenkins API

Azure DevOps Import

Migration Assistant includes a dedicated Azure DevOps importer that extracts comprehensive data from your Azure DevOps organization.

What Gets Imported

• YAML Pipelines - Modern Azure Pipelines definitions from azure-pipelines.yml files
• Classic Build Definitions - Legacy build configurations (flagged as anti-patterns)
• Classic Release Pipelines - Release definitions and deployment stages
• Tasks and Templates - Referenced tasks and reusable template dependencies
• Service Connections - External service integrations
• Variable Groups - Shared variables and secret references
• Secure Files - Certificate and key file references
• Agent Pools - Build agent configurations
• Environments - Deployment target environments

Pipeline Types

Azure DevOps pipelines are handled differently based on their type:

YAML Pipelines

• Source file (azure-pipelines.yml) is attached to the migration workspace
• Pipeline content is viewed and edited from the repository file
• Template and task references are tracked for dependency mapping

Classic Pipelines

• Build and Release definitions are imported as JSON
• No in-repository file exists, so the imported definition is the source of truth
• Can be viewed through the "View Pipeline Definition (JSON)" option

Import Methods

JSON Upload

Upload a pre-exported JSON file containing your Azure DevOps data:

1. Navigate to Migration Assistant → Import → JSON
2. Upload your Azure DevOps export file
3. Follow the mapping wizard to configure your migration

Direct Azure DevOps Connection

Connect directly to your Azure DevOps organization for live data import:

1. Navigate to Migration Assistant → Import → Azure DevOps
2. Provide your Azure DevOps organization URL and authentication credentials
3. The importer will extract data directly from your Azure DevOps REST API

Anti-Pattern Detection

The Azure DevOps importer automatically identifies legacy patterns that should be modernized:

• Classic Build/Release pipelines - Flagged for conversion to YAML
• Deprecated tasks - Tasks that have newer alternatives
• Security anti-patterns - Configurations that don't follow current best practices

These anti-patterns are highlighted during the mapping process to help prioritize modernization efforts.

Post-Import Discovery

After an import completes, Migration Assistant automatically analyzes your source data to map reusable-code dependencies. Discovery results surface in the dashboard and detail panels to help you plan migration order.

Jenkins Shared-Library Discovery

Migration Assistant runs post-import discovery for Jenkins shared libraries, building a comprehensive inventory of library dependencies:

• Library Surface Scanning - Inventories all shared-library entrypoints and available functions
• Usage Resolution - Associates each imported job with the library elements it uses
• Dependency Mapping - Creates intra-library reference edges and job entrypoint relationships
• Inline Script Analysis - Analyzes jobs with inline pipeline scripts without requiring repository mapping

The discovery process uses tree-sitter Groovy parsing to extract structural facts from your Jenkins pipelines and shared libraries, providing detailed insights into library usage patterns across your organization.

Azure DevOps Pipeline Template Discovery

Migration Assistant analyzes imported Azure DevOps pipelines to identify reusable template references and track their availability:

• Resolves template chains - Follows extends and template references to build the complete dependency graph
• Cross-repository resolution - Identifies templates in other repositories within your workspace
• File status tracking - Verifies whether referenced template files actually exist
• Dependency mapping - Creates a persistent graph of template relationships

Pipeline entities display status badges in the dashboard and detail panels:

Discovery runs automatically after import, but you can trigger it manually from Migration Assistant → Dev Tools → Run Discovery, selecting the organization or a specific instance and monitoring progress in the cargo job logs.

Entity Dependencies and Impact Analysis

After discovery runs, Migration Assistant builds a persistent dependency graph that powers the Dependencies and Used by sections in every entity detail panel.

Dependencies (forward edges)

When you open a job's detail panel or in-editor view, the Dependencies section lists every entity that job relies on — reusable pipeline elements (templates, shared-library functions) and task plugins discovered from the pipeline source. Each entry shows the dependency's name, type, and migration lifecycle status so you can assess readiness at a glance. Container-level entries (e.g., a shared library) are collapsed when a more specific element from that library is already listed, keeping the list focused.

Used by (reverse edges)

Plugin entities (ADO tasks, Jenkins plugins) display a Used by section listing every job and template that references them. This impact surface lets you understand the blast radius of a plugin before you migrate or deprecate it.

Mapping Wizard

The mapping wizard guides you through configuring how your legacy CI/CD data translates to GitHub Actions.

Repository Mapping

Match legacy jobs to GitHub repositories using:

• Fuzzy matching - Automatic suggestions based on legacy job names and repository names
• Manual selection - Choose specific repositories from your connected GitHub organization
• Bulk operations - Apply mappings to multiple jobs at once

Plugin Mappings

Map source plugins or tasks to equivalent GitHub Actions:

• Suggested mappings - Common plugin/task-to-action mappings are pre-configured
• Custom mappings - Define your own mappings for organization-specific plugins or tasks
• Action parameters - Configure how plugin or task settings translate to action inputs

Credential Mappings

Map source credentials to GitHub Secrets:

• Secret naming - Define how source credential IDs map to GitHub Secret names
• Scope mapping - Choose repository-level or organization-level secrets
• Security notes - Guidance on recreating sensitive credentials in GitHub

Migration Settings

Configure job-level migration preferences:

• Workflow naming - How legacy job names become GitHub workflow file names
• Trigger mapping - How source triggers translate to GitHub workflow triggers
• Environment mapping - Map source build environments to GitHub environments

Not Mapped Option

When configuring migration mappings, you can set any mapping to "Not Mapped" to exclude it from the migration process:

• Removing mappings: Switch a previously configured mapping back to "Not Mapped" to remove it
• Success feedback: The save operation shows the count of removed mappings alongside created and updated counts
• Persistent state: "Not Mapped" selections are preserved when you reload the page

This is useful when you initially map a component but later decide it shouldn't be included in the migration.

Migration Batches

Migration Batches let you organize migration entities into curated collections for coordinated migration efforts. A batch is a cross-source collection of jobs and reusable pipeline elements that provides:

• Centralized Progress Tracking - View migration status across all batch members
• Repository Management - Configure repositories for batch members inline
• Scope Management - Add or remove entities from batches as needed
• Status Updates - Change migration status for individual entities within the batch

Creating and Managing Batches

Access Migration Batches from the Batches tab in Migration Assistant:

1. Create a batch - Click "Create Batch" and provide a name and description
2. Add entities - Use the entity picker to add jobs and reusable pipeline elements
3. Configure repositories - Set repositories for entities that need them
4. Track progress - Monitor migration status with live progress rollups

Batch Scope and Readiness

Batches can include jobs (individual CI/CD jobs from your legacy system) and reusable pipeline elements (functions and templates from shared libraries). Entities show "Not configured" when they lack a required repository, but this doesn't prevent adding them to batches — you can resolve repository configuration directly from the batch detail panel.

Batch Execution

Once a batch is configured, you can run migrations as background agent jobs directly from the batch detail page. The Batch Execution panel lets you start, stop, retry, and restart the agent across all batch members.

• Start — launches the migration agent for all ready batch members, respecting a per-batch concurrency cap so jobs run in parallel without overwhelming your repositories
• Stop — cancels in-progress agent runs for the batch
• Retry — re-queues failed items without restarting items that already succeeded
• Restart — resets all batch members and starts fresh

Dependency gating ensures that items with unresolved dependencies wait until their prerequisites complete before the agent picks them up. If a dependency cycle is detected, the affected items are exempted from gating so the batch can still make progress.

Progress updates stream in real time via the clickable progress-bar legend at the top of the batch view. Click any segment (for example, In Progress or Ready for Review) to filter the batch scope grid to items in that state.

Service Catalog Integration

Migration Assistant integrates with the Service Catalog to provide visibility into your migration progress:

Migration Nodes

• Migration Assistant Container nodes - Represent the overall migration project
• Migration Assistant Job nodes - Individual jobs from your legacy CI/CD system
• Dependency visualization - See relationships between migrated and existing workflows

Graph Views

Migration components appear in both:

• Organization graph - Overall migration progress across your organization
• Per-service detail graph - Migration status for specific services and repositories

AI-Assisted Migration

Once your data is imported and mapped, use the GenAI Editor's migration mode for AI-assisted conversion.

Migration Mode Features

Enhanced Context

• Source-specific system prompts (Jenkins-aware AI assistance)
• Access to original source files (Jenkinsfiles, plugin configurations)
• Migration mapping context for accurate conversions

Specialized File Tree

• Source-side nodes showing original CI/CD files
• GitHub Actions workflow files for comparison
• Migration mapping references

Custom Syntax Support

• Jenkinsfile syntax highlighting with custom Monarch tokenizer
• GitHub Actions YAML with migration-aware suggestions
• Side-by-side comparison views

Azure DevOps Context

• Azure DevOps-aware AI assistance with understanding of ADO-specific concepts
• Access to original pipeline YAML, Classic definitions, and variable groups
• Automatic mapping of ADO expressions (${{ }}, $( ), $[ ]) to GitHub Actions syntax
• Multi-stage pipeline conversion to GitHub Environments
• Service connection to GitHub Secrets mapping
• Azure Pipelines YAML syntax highlighting alongside side-by-side comparison with the GitHub Actions format

Migration Workflow

1. Select a job from the Migration Assistant dashboard
2. Click "Migrate in Editor" to open the GenAI Editor in migration mode
3. Review the source - examine the original job configuration from your source CI/CD instance
4. Use AI assistance - ask the Expert Workflow Agent to convert the job to GitHub Actions
5. Refine and test - iterate on the generated workflow with AI help
6. Create pull request - submit the new GitHub Actions workflow for review

Job + Dependencies Migration Flow

When migrating jobs that depend on legacy reusable-pipeline functions, Migration Assistant supports a comprehensive workflow that includes both the job and its dependencies:

Workspace Configuration

For jobs with legacy dependencies, you can choose "Include Building Block repositories in this workspace" during migration launch. This creates a workspace containing:

• Job's repository - where the calling job is defined
• Legacy reusable-pipeline repository - read-only context with the original function implementations
• Building Block destination repository - where new Building Block Workflows will be created

Two-Step Migration Process

The AI agent follows an explicit two-step pattern when both job and dependency mappings are configured:

1. Create Building Block Workflows - Convert legacy library functions to Building Block Workflows in the destination repository
2. Update the calling job - Modify the job's pipeline to invoke the new Building Block Workflow instead of the legacy function

This ensures complete migration where the job actually uses the converted workflows, not just creates them.

Legacy Repository Handling

The legacy reusable-pipeline repository appears in the workspace as read-only context:

• Source files are attached as linked files when paths are known
• The AI can read implementations but cannot write to the legacy repository
• Repository context clearly identifies it as legacy source for migration reference

Agent Communication

While the migration agent is running, it can surface questions and status updates directly in the Migration Assistant interface without requiring you to open the GenAI Editor.

• Status reports — the agent posts progress updates as it works through each migration step, visible in the batch detail panel
• Questions — when the agent needs clarification (for example, which target repository to use or how to handle an ambiguous mapping), it pauses and asks you directly in the chat thread attached to that batch item
• Resolve in chat — reply to the agent's question in the chat thread; the agent resumes automatically once it receives your answer
• BLOCKED — if the agent cannot proceed and no user response resolves the issue, the item moves to a terminal BLOCKED state. You can review the reason, update your mappings or repository configuration, and then retry the item

This communication loop means you can monitor and guide large batch migrations without manually opening each workspace.

Best Practices

Before You Start

• Audit your source CI/CD instance - Review active vs. inactive legacy jobs
• Document custom plugins or tasks - Note any organization-specific plugins or tasks that need special handling
• Plan repository structure - Decide how legacy jobs map to your GitHub repository organization
• Prepare credentials - Plan how to recreate sensitive credentials in GitHub Secrets

During Migration

• Start with simple jobs - Begin with basic build jobs before tackling complex pipelines
• Validate mappings - Test repository and plugin mappings with a few jobs before bulk operations
• Use Building Blocks - Create reusable workflow templates for common patterns
• Iterate incrementally - Migrate and test jobs in small batches

After Migration

• Test thoroughly - Run migrated workflows in a test environment before production use
• Update documentation - Ensure team documentation reflects the new GitHub Actions workflows
• Train your team - Help developers understand the new GitHub Actions-based workflows
• Monitor and optimize - Use CodeCargo's compliance and insights features to improve your workflows over time

Troubleshooting

Common Import Issues

Jenkins Connection Failures

• Verify Jenkins URL and authentication credentials
• Check network connectivity and firewall rules
• Ensure Jenkins API is enabled and accessible

Incomplete Data Import

• Review Jenkins permissions for the importing user
• Check for plugin compatibility issues
• Verify Jenkins version compatibility

Mapping Problems

Repository Matching Failures

• Use manual repository selection for complex job names
• Check GitHub App permissions for repository access
• Verify repository names and organization settings

Plugin Mapping Gaps

• Create custom mappings for organization-specific plugins
• Consult GitHub Actions marketplace for equivalent actions
• Consider workflow redesign for deprecated Jenkins plugins

Migration Issues

AI Conversion Problems

• Provide more context about the original job's purpose
• Break complex jobs into smaller, focused workflows
• Review and adjust migration mappings for better AI context

Workflow Validation Failures

• Use CodeCargo's compliance features to identify issues
• Test workflows in a development environment first
• Iterate with the AI agent to resolve syntax and logic problems

Setup Flow

The Jenkins importer uses a three-step setup process designed to keep credentials secure:

1. Log in to the registry - Authenticate with the CodeCargo container registry using your generated token
2. Download credentials file - Download a pre-populated .env file and edit it with your Jenkins credentials in your preferred editor
3. Run the importer - Execute the Docker container using the credentials file

This approach ensures that sensitive credentials like Personal Access Tokens and Jenkins API tokens never appear in your shell history.

Credential File Management

The downloaded .env file includes:

• Pre-filled CodeCargo API credentials
• Template entries for Jenkins URL, username, and API token
• Import mode configuration (if not using the default merge-keep mode)

After completing the import, delete the credentials file to remove sensitive tokens from your local filesystem.