Migration
Migrating Jobs
AI-Assisted Migration
Once your data is imported and mapped, the actual conversion to GitHub Actions happens with AI assistance in the GenAI Editor's migration mode. You can migrate jobs one at a time from the dashboard, or at scale using Migration Batches and the migration agent.
Migrating a Single Job
- Select a job on the Pipelines dashboard to open its detail panel
- Click Migrate in Editor to open the GenAI Editor in migration mode
- Review the source - examine the original job configuration from your source CI/CD instance
- Use AI assistance - ask the migration agent to convert the job to GitHub Actions
- Refine and test - iterate on the generated workflow with AI help
- Create pull request - submit the new GitHub Actions workflow for review
Migration Context
The AI agent has full context of your migration mappings, so it can automatically apply your plugin-to-action mappings and credential references when generating GitHub Actions workflows.
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
- 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
Migrating Jobs with Dependencies
Many legacy jobs depend on reusable pipeline elements — Jenkins shared-library functions or Azure DevOps templates. Migration Assistant handles both cases: dependencies that are still legacy, and dependencies that have already been migrated to Building Blocks.
Already-Migrated Dependencies
When you launch Migrate in Editor for a job whose dependencies have already been migrated, a pre-checked checklist of those resolved dependencies appears on the launch page, Preparing Migration Editor. Each entry shows the dependency's existing Building Block and its associated legacy repository.
- Pre-checked entries are included in the workspace by default, bringing their Building Block repository and legacy repository in as read-only context — the same behavior batch migrations use.
- Deselect an entry to exclude that Building Block's repository from the workspace. Re-checking it adds it back before you launch.
This lets you control exactly which already-migrated dependencies are available as context during the migration, without having to configure them manually.
A Building Block Shared from Another Organization
You can map a job to a building block another organization has shared with yours. Those are the blocks that show Shared from in your Building Blocks catalog, including blocks in the plan's building block home. Building Blocks has to be available on your organization's plan. If it is not, contact your CodeCargo administrator.
The migration workspace mounts that repository read-only, so the migration calls the block instead of changing it. A workflow mounts its file. An action mounts the whole repository, so action.yml and its supporting files are present. The converted workflow calls the block in the owning organization's repository, at that path, pinned to the commit of the branch, tag, or release the source tracks. A blueprint counts once it is realized as a block shared with you. Additional building blocks on the mapping follow the same rule.
When you save a mapping, a block that is not shared with your organization is skipped. When you run the migration, a block that is no longer shared is left out of the workspace. Disabling the block, or deactivating its repository, does the same. You cannot reference or mount another organization's building block by name or path alone.
When a shared block cannot be pinned
The migration stops if the source has not synced that version to a commit yet. Wait for the sync, then start again. At Build level 3, it also stops when a builder in another organization is no longer shared. In the organization that owns the source, open Manage Shares and share the source with this organization again.
Legacy Dependencies: Job + Dependencies Flow
When a job depends on reusable pipeline elements that haven't been migrated yet, you can migrate the job and its dependencies together.
Workspace Configuration
Choose "Include Building Block repositories in this workspace" during migration launch. This creates a workspace containing:
- The job's repository - where the calling job is defined
- The legacy reusable-pipeline repository - read-only context with the original function implementations
- The 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:
- Create Building Block Workflows - Convert legacy library functions to Building Block Workflows in the destination repository
- Update the calling job - Modify the job's pipeline to invoke the new Building Block Workflow instead of the legacy function
This ensures a complete migration in which the job actually uses the converted workflows, not one that merely 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
Read-Only Legacy Context
The AI agent will refuse requests to modify legacy reusable-pipeline repositories. These exist solely as source material for creating new Building Block Workflows.
Includes from Another GitLab Project
When you convert a GitLab job, an include of a file or a component from another project follows that file's mapping. A local include from the job's own project is converted with the job, not copied in.
- No mapping. The migration copies what this pipeline uses into the job's own workflow. It mounts the file's repository read-only and attaches the file, and does the same for every file that include pulls in that also has no mapping. It does not change those files, and it does not pause to ask where the include's output goes.
- Has a mapping. The job's workflow calls the building block or reusable workflow the mapping names. The file is not copied in, including when an unmapped include pulls it in. What that mapped file includes is left for its own conversion.
If the include names a ref, the attached file is that repository's default branch. The migration notes that it read the default branch rather than the ref the pipeline names.
A copied include is not shared
The copy does not follow later changes to the template, and each pipeline that uses the template gets its own. Map the include to a building block when those pipelines should keep calling one workflow.
Converting that included file on its own, with no mapping, still pauses to ask where its output goes. See No Destination Mapping.
Migration Status Lifecycle
Every job and reusable pipeline element carries a migration status. It drives the progress bars, the Statuses filter, and the completion figures throughout Migration Assistant.
| Status | Meaning |
|---|---|
| Not started | Imported, with no migration begun. Add it to a batch or migrate it from the editor. |
| Queued | In a batch, waiting for the batch to run it. While its dependencies in the batch run first, it shows Waiting on dependency or Waiting on dependencies. |
| In progress | The migration agent is working on it. |
| Needs input | The agent asked a question and is paused until someone answers. See Agent Communication. |
| Blocked | The agent stopped: something outside the workspace needs to change before the migration can succeed. |
| Ready for review | The agent finished. Review the migrated code, then open a pull request. |
| PR open | The pull request is open. Merging it completes the migration. |
| Migrated | The pull request was merged. |
| Failed | The migration failed. The execution log in the item's detail panel says why. |
| Canceled | The run was stopped. Retry the item to run it again. |
| Skipped | You chose Skip — don't migrate this item. Execution ignores it. |
| Done externally | You chose Mark done externally: it was migrated outside a tracked migration workspace. |
| Uses existing | Its mapping points at an item that already exists, or that another item in this migration builds, so there is nothing to migrate. Items that use it don't wait for it. |
Set Skipped or Done externally from the status menu in the item's detail panel, and undo them there with Unskip or Unmark done externally. Start Migration Over… in the same menu resets an item that has started and runs it fresh. For an item in PR open, close the pull request on GitHub first.
For a GitHub Actions workflow, which converges onto a building block rather than migrating, Migrated reads Converged and Uses existing reads Already converged: the workflow already calls the block it maps to. The Migration Plan uses converged differently, for a pipeline that is Migrated or Done externally. See How Conversion Is Going.
Progress-Bar Buckets
Progress bars and their legends group the statuses into buckets. The Statuses filter groups them the same way.
| Bucket | Statuses |
|---|---|
| Done | Migrated, Done externally |
| Awaiting review | Ready for review, PR open |
| In progress | In progress |
| Action needed | Needs input, Blocked |
| Failed | Failed |
| Won't migrate | Canceled, Skipped, Uses existing |
| Not started | Not started, Queued |
The completion figure counts Migrated, Done externally, and Skipped items as complete. Skipping something is a decision, not unfinished work. Failed and canceled items never count.
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 Migration Assistant → Pipelines → Batches:
- Create a batch - Click New batch, enter a Batch Name and an optional Description, and click Create batch
- Add entities - Use the entity picker to add jobs and reusable pipeline elements
- Configure repositories - Set repositories for entities that need them
- 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.
Migration Ready Status
Batch members are considered "migration ready" when they have a configured repository. The batch progress view shows both configured and unconfigured entities, with aggregate counts for planning purposes.
Dependencies Not in a Batch
After you add items, CodeCargo offers the items they depend on that no batch holds, including the reusable pipeline element that builds the block a job is mapped to. A dependency you add migrates first, and the items that use it wait for it.
A notice on the batch keeps offering those items while a member uses one that no batch holds. It names a single item, and counts them when there are several. Its Add N to this batch button (Add it to this batch for one) adds them all. Add to batch on a dependency in an item's detail panel still adds just that one.
Only an item a batch can hold is offered. An item a batch cannot take, such as a shared library kept only as a job's dependency, is left out.
No Destination Mapping
A reusable pipeline element — a Jenkins shared-library function or an Azure DevOps template — needs a mapping that says where its converted output goes. A job does not: its workflow is written in that job's repository.
Next to repositories not configured, the batch shows destinations not mapped in the batch header, the execution panel, and the batch list. Open the item and Destination in the Readiness section links to the Mappings page.
You can still start. The confirmation lists those items and warns that each one will run, then stop to ask where its output goes. Map a destination on the Mappings page first to avoid that pause.
A missing source repository is reported on its own, and that item is not ready to run. An element mapped to a Building Block blueprint is not included in this count. If the blueprint itself has no destination, the batch holds that item until you set one.
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 at the top of the page lets you start, stop, and retry the agent across batch members:
- Migrate Queued Items - Launches the migration agent for the ready batch members. Start applies to your current selection in the batch scope grid: check specific rows to run just those (the button then reads Migrate Selected Items), or start with nothing selected to run the whole batch. Before dispatching, the confirmation dialog lists unresolved template references separately from ordinary unmet dependencies, so you can tell a missing source from an item that's simply waiting its turn.
- Stop - Cancels in-progress agent runs for the batch and holds the items still queued
- Retry N failed - Re-queues failed items without restarting items that already succeeded
- Open PRs and Check PR Status - Open pull requests for items that are ready for review, and re-read the state of open pull requests from GitHub
To reset a single item and run it fresh, choose Start Migration Over… from the status menu in its detail panel.
The agent respects a per-batch concurrency cap so jobs run in parallel without overwhelming your repositories. If you have more ready items than the cap allows, the remaining items queue automatically and start as running items complete.
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 awaiting review) to filter the batch scope grid to items in that bucket.
Items Marked No Longer Used
A GitHub workflow marked No longer used can already be in the batch, but the batch does not start or retry it. When you start the batch, the confirmation says how many of these workflows it will skip, and why. Retry N failed leaves them out too.
The add-items picker does not list them, and an item's dependency list does not offer Add to batch for one. The batch page counts them as N no longer used, and the item's panel reads Won't run: discovery no longer finds this workflow. Open the workflow to see why it was kept, or to Remove it. See No Longer Used.
The same mark on a Jenkins, Azure DevOps, or GitLab item does not hold it. That item still runs.
Building Block Blueprints in Batches
Building Block Blueprints — approved during pattern review in a Pipelines wave — are batch members alongside jobs and reusable pipeline elements. A blueprint describes the block a pattern needs: its name, destination, and interface of inputs, outputs, and secrets.
When a batch contains a blueprint and items that call it, CodeCargo dispatches the blueprint first, within the same batch concurrency cap. The consumers hold until the blueprint's pull request merges and the block is registered, then start automatically.
A blueprint can only be dispatched once it has a destination — the repository and path where its block will live. If a destination is missing, every start path holds that item and the batch page offers an inline control to set it; saving the destination releases the item immediately, without waiting for the next dispatch cycle.
Building Block not created
If a blueprint's producer pull request merges but no block was registered — or a migrated shared-library function's output was never registered as a block — the item shows a Building Block not created advisory. Use its Retry action to reconcile — CodeCargo re-checks the destination and picks the block up if it exists, or re-runs the producer if it doesn't.
A Job Mapped to a Building Block
A job mapped to a building block is migrated. The migration writes a workflow in that job's repository that calls the block. The workspace mounts the block read-only so the migration can call it without changing it.
When the block already exists, the job runs when you start the batch. A GitHub workflow that already calls that block does not: it shows Already converged, the GitHub name for Uses existing, and the batch does not run it.
When another item in this migration builds the block, the job stays queued until that block exists, then runs. The item that builds it does not have to be in this batch. After you add the job, the batch offers to add that item too; see Dependencies Not in a Batch. Retry on the job before then queues it, and it still waits for the block. If Migrate Queued Items starts nothing, these jobs count among the items waiting on building blocks.
The wait ends when the block is registered, or when the blueprint that item is mapped to is realized. It also ends if you mark that item skipped or done externally, delete it, or remove the mapping that would build the block, including by deleting its blueprint. Merging that item's pull request does not release the job by itself. If the block was not registered, use Retry on the Building Block not created advisory.
While the job is queued, anything in the batch that depends on it waits. A reusable pipeline element mapped to an existing or planned building block shows Uses existing. It is not run, and the items that depend on it do not wait for it.
Agent Communication
While the migration agent is running, it surfaces questions and status updates directly in the Migration Assistant interface, so you can monitor and guide large batch migrations without opening each workspace:
- 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 Blocked. Review the reason, update your mappings or repository configuration, then choose Start Migration Over… from the status menu in its detail panel
Not every pause comes with a question you can answer in place. When the agent replies conversationally rather than asking a structured question, the panel shows its message together with an Answer in the editor link that opens the workspace on the exact conversation holding it — reply there and the item resumes. Questions that carry suggested options or additional context keep their inline answer form, so you can respond without leaving the batch view.
When the link isn't available
If the workspace behind the conversation no longer exists, the panel keeps the inline answer form so you can still unblock the item.
Pipelines Waves
A Pipelines wave groups jobs and reusable pipeline elements to migrate as a unit. Open Migration Assistant → Pipelines → Waves and click New wave. Give it a name, an optional description, and a Migration approach: Mirror existing or Redesign.
The wave's page opens on an overview of its progress, then works through four stages:
- Build the scope - Pick the jobs and reusable pipeline elements this wave migrates.
- Run planning - Group the scope into patterns of look-alike pipelines: copies of the same pipeline, and pipelines that use the same tasks, templates, and libraries. Run deep analysis also has an AI agent name and describe each pattern, draft a building block recommendation, and profile every pipeline. It takes a few minutes and uses AI.
- Review patterns - Confirm each pattern and the building block it should migrate onto.
- Generate & run batches - Generate batches from the patterns, then run them and track their progress.
Running planning or deep analysis, and starting a batch, each need a permission beyond managing Migration Assistant.
In a Migration Plan's sandbox, a standalone wave can be brought into the plan with Bring into the plan on the Outside the plan card of Schedule Waves. Its pipelines then convert with their repositories' waves, and the wave here becomes read-only. Undo on that card reopens it.
Review Patterns
Migration Assistant identifies patterns that recur across your imported jobs — shared-library functions and pipeline templates that many jobs call — as candidates for Building Blocks, CodeCargo's reusable workflow components.
Each confirmed pattern gets a Building Block Blueprint: a description of the block the pattern needs, including its name, destination repository and path, and its interface of inputs, outputs, and secrets. During pattern review you can edit that interface before confirming; confirming the pattern also approves its blueprint. Blueprints later become batch members that are migrated ahead of the jobs that call them — see Building Block Blueprints in Batches.
Jobs That Call More Than One Family
A job can call more than one pipeline family. Pipelines That Call More Than One Family says which family it belongs to. In a Pipelines wave, five or more jobs that call the same families in the same order share one pattern. The pattern is named for those families in that order, such as Image build + Chart deployment. Jobs that call the same families in a different order are not in it. Fewer than five sit with their own family, and the reason names the other families that job also runs.
That shared pattern has no building block of its own. Each job's converted workflow calls every family's building block, in that order, one job per call. The call uses that job's own values as with:, its condition as if:, and its dependencies as needs:. What every job in the pattern also runs outside a family stays in the workflow. Analysis names the pattern, describes it, and profiles each job. It does not propose a building block.
Confirm each of those family patterns, with its building block, before you confirm the shared pattern. Until then, confirm is refused and names the families still waiting. Each job is mapped onto its own family's building block, and the other families' building blocks are additional blocks on the same mapping. A job you already mapped keeps the target you set, and still holds every family's building block.
A family keeps a pattern of its own, on its template, when at least two jobs in the wave call it, even when none of them sits with it. Its building block is still planned. A job on another pattern that calls it waits for that block, and can call it.
A Wave the Plan Converts
When a migration plan converts pipelines in this organization, it writes a wave here, named for the plan's wave. The plan sets that wave's pipelines, patterns, mappings, and batches. The wave's page says so in a banner, such as Converting acme's migration plan, wave 2, with Open in the plan. Its scope, planning, pattern and batch-membership edits are off. A request that tries one anyway, such as from an MCP client, is refused and names the wave. Change what the wave converts on the Migration Plan.
You can still run and review its batches: start them, stop them, retry failed items, start an item over, and open or check their pull requests. You can also edit one pipeline's mapping.
Pipelines in that wave join only the batches the plan makes. Adding one to a batch you created is refused.
While the plan holds the wave, a Replace all import that would drop its pipelines is refused. See When a Replace Import Is Refused. Remove the wave on Schedule Waves, and the wave here becomes an ordinary wave you can change.
Troubleshooting Migrations
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
Next Step
Migrating from Azure DevOps? Prepare for Rewire does not wait for this phase. Once repositories are on GitHub — moved with Migrating Repositories or with gh ado2gh — it cleans up lingering Azure DevOps references and rebinds your pipelines onto the copies, so they keep building until you migrate them.
