CodeCargo logo

Migration

Importing Data

Import Overview

Before pipelines can be mapped and converted, their data has to be in Migration Assistant. There are three ways to bring it in:

  • Sync pipelines from a connection - On an Azure DevOps organization or GitLab group connected in CodeCargo, turn on pipeline sync (Azure DevOps, GitLab) and CodeCargo imports for you. There is no container to run.
  • Run the importer - A containerized importer connects to your live Jenkins instance, Azure DevOps organization, or GitLab instance and extracts data directly through its API. It works with every source, including Jenkins, Azure DevOps Server, and a GitLab group that is not connected.
  • Upload a JSON export - If you already have a pre-exported JSON file (for example, produced by an earlier importer run or shared by another team), upload it under Migration Assistant → Pipelines → Import → JSON and map it in the wizard before anything is saved. See Uploading a JSON Export.

Every importer starts from the Import button on the Pipelines dashboard (Migration Assistant → Pipelines in the sidebar), which lists one card per source system plus the JSON upload.

The Import Migration Data page with four cards: Import from Jenkins, Import from Azure DevOps, and Import from GitLab, each with a Start Import button, and Import from JSON with an Upload JSON button.

In every case, only metadata and configuration are imported. Sensitive credential values are never extracted or stored — credentials are imported as definitions only, and you recreate their values as GitHub Secrets during mapping.

Setting Up the Importer

The Jenkins, Azure DevOps, and GitLab importers run as a Docker container on your machine (or any host with network access to your source system) and connect back to CodeCargo using a downloaded credentials file. Setup follows three steps, designed so that sensitive tokens never appear in your shell history:

  1. Log in to the registry - Authenticate with the CodeCargo container registry using your generated token
  2. Configure and download the credentials file - Configure the connection in the CodeCargo UI, then download the generated .env file
  3. Run the importer - Execute the Docker container using the credentials file
Where the importer runs. The importer container runs on your machine, or any host in your network, with the downloaded .env credentials file. It reads the source system's API (Jenkins, Azure DevOps, or GitLab) inside your network and sends metadata and configuration to CodeCargo over HTTPS. The source token you fill into the .env file stays on your machine, and credential values are never extracted.Your networkYour machineCredentials file (.env)CodeCargo API credentialsSource token, filled inlocally, never uploadedImporter containerdocker run withthe .env fileSourcesystemJenkins, ADO,or GitLabAPICodeCargoJobs, plugins,credential names— never valuesHTTPS
The importer runs inside your network. Only metadata and configuration reach CodeCargo.

Configuring the Connection

You configure the importer in the CodeCargo UI before downloading the credentials file, rather than hand-editing the .env file afterwards:

  • Jenkins - Provide your Jenkins controller URL. localhost is rejected, since inside the importer's container localhost refers to the container itself rather than your host machine; use http://host.docker.internal:8080 for a Jenkins instance running locally.
  • Azure DevOps - Provide your organization name (a full URL is rejected here) and choose an import scope: specific repositories via a CSV list, specific project names, or everything in the organization.
  • On-premises Azure DevOps Server - Toggle On-Premises Server under the organization field to switch to a full server URL. The scope CSV template is automatically stamped with the URL's collection segment, which the importer matches against.
  • GitLab - Provide a full http:// or https:// instance URL (prefilled https://gitlab.com) and a Group when the host is gitlab.com. Loopback addresses (localhost, 127.0.0.1, and similar) are rejected, since inside the container they refer to the container itself; use http://host.docker.internal:... for GitLab running on your machine. Don't paste a gitlab.com group page as the URL — the host must be the instance host. On a self-managed instance, leave Group empty to import every group.

Once your configuration is complete, the page shows a summary of what will be downloaded — organization or server, scope, and import mode. Click View file contents if you want to inspect the raw .env file before downloading. The Download button stays disabled until your configuration is complete, and if you change settings after downloading, a warning lets you know the downloaded file is stale.

The Download the credentials file card for Azure DevOps: an Import mode selector set to Merge - keep items not in this import (default), and a summary with Organization acme, Scope Projects: Commerce, Analytics, Infrastructure, Mobile, To fill in yourself Azure DevOps PAT, and the import mode, with View file contents, Copy, and Download.

The Credentials File

The downloaded .env file includes:

  • Pre-filled CodeCargo API credentials
  • Template entries for your source-system authentication — Jenkins URL, username, and API token, your Azure DevOps personal access token, or your GitLab token
  • Import mode configuration (if not using the default merge-keep mode)

Fill in the source-system authentication entries locally in your editor — these secrets stay on your machine and are never sent to or stored by CodeCargo. After the import completes, delete the credentials file to remove sensitive tokens from your local filesystem.

When a Replace Import Is Refused

When this organization converts pipelines for a migration plan, those pipelines sit in a wave the plan writes here. An import with Import mode set to Replace all that would drop them is refused, and the refusal names the wave. Use a Merge mode instead. Replace all for another source or instance still runs.

A replace is allowed again once that wave holds no pipelines, or you remove the wave from the plan.

Sources Behind a Proxy

If Jenkins, Azure DevOps, or GitLab sits behind an identity-aware proxy — such as Cloudflare Access, an API gateway, or a corporate reverse proxy — the importer also sends the headers that proxy issued. The downloaded credentials file includes a commented example next to the source token. Uncomment the line for your source and replace the placeholders with the values from the proxy:

Shell
JENKINS_EXTRA_HEADERS={"CF-Access-Client-Id":"<client-id>","CF-Access-Client-Secret":"<client-secret>"}

Azure DevOps uses ADO_EXTRA_HEADERS and GitLab uses GITLAB_EXTRA_HEADERS. The value is a single line of JSON mapping each header name to its value. Leave the line commented when no proxy sits in front of the source; an untouched file sends no extra headers.

The values are proxy credentials. They stay in the file on your machine, and a run logs only the header names. Don't set a header the importer already sends, such as Authorization or PRIVATE-TOKEN — put source credentials in the importer's own token variable. A Cookie header is the exception: it is combined with any session cookie the source requires. A value that is not valid JSON, or that names a header the importer already sets, stops the run at startup and names the variable to fix.

Watching an Import

When you run the Jenkins, Azure DevOps, or GitLab importer, entities are applied as they arrive. The import page shows a live banner for the run in progress — including a Stop import button — and an Import runs card with recent runs.

A live banner reading An import from Azure DevOps is running, naming jlee on build-agent-07, when it started and its last activity, with a Stop import button; below it the Import runs card lists the running run with 2 of 4 units and 611 of 1,057 items applied, and two completed runs with their driver, duration, created, updated, and deleted counts, and Post-import steps done.

If the importer is interrupted, run the same Docker command with the same credentials file. It continues from where it left off; nothing already imported is rolled back.

While an import is running for an instance, you cannot change that instance's entities, add them to batches or waves, or run discovery and planning against them. Wait for the import to finish, or click Stop import on the import page. Only one import can run at a time for each source (Jenkins, Azure DevOps, or GitLab).

An instance page banner: An import is running, dev.azure.com/acme, started by jlee on build-agent-07. Entity edits, mappings, batches and waves for this instance are locked until it finishes.

Azure DevOps Import

Start an Azure DevOps import under Migration Assistant → Pipelines → Import → Azure DevOps. The importer extracts data directly from the Azure DevOps REST API.

Use this importer for Azure DevOps Server, or for a scope you name yourself. A connected organization can sync its pipelines instead; see Import Overview.

What Gets Imported from Azure DevOps

  • 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

  • The pipeline source file (e.g. azure-pipelines.yml) lives in its repository. When you launch a migration workspace, the file is attached as a read-only linked file so the AI agent can read it directly from disk — the content is not copied onto the entity record.
  • Template and task references are tracked for dependency mapping.

Classic Pipelines

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

Repository Linking

For YAML pipelines to appear correctly in the migration workspace, ensure the source repository is linked and active in your CodeCargo organization. See GitHub Integration for how repositories are connected.

When importing Azure DevOps pipelines, Migration Assistant resolves each pipeline's repository link using two facts, in order:

  1. Relocation map — if the source repository was migrated to GitHub with GitHub Enterprise Importer, the pipeline links to its migrated repository. Migrations run from Migrating Repositories record this relocation directly; migrations run with gh ado2gh outside CodeCargo are traced from their Migration Log issue.
  2. Repository name match — for pipelines whose repository has no relocation record yet (it was never migrated, or an external migration hasn't been traced yet), Migration Assistant falls back to matching against your CodeCargo repository names.

A pipeline's existing repository link is never cleared by an import that can't resolve a reference — a link is only ever replaced by a positive match, so re-importing after editing your source data can't accidentally undo a manual mapping.

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.

GitLab Import

Start a GitLab import under Migration Assistant → Pipelines → Import → GitLab. The importer connects to the GitLab API for gitlab.com or your self-managed instance.

On gitlab.com (and its subdomains) a Group path is required before you can download the credentials file — a pasted group URL is rejected, and surrounding slashes are stripped. On a self-managed instance, leave Group empty to import every group. After downloading, set GITLAB_TOKEN in the file (read_api scope; a Reporter or Maintainer role on the group is sufficient) and run the docker run command shown on the page.

Use the importer for a group that is not connected. A connected group can sync its pipelines instead; see Import Overview.

What Gets Imported from GitLab

  • Groups and Subgroups - Each group, with the projects it holds
  • Pipelines - One per project with a CI file: its stages, includes, runner tags, environments, and how many pipeline schedules it has
  • CI/CD Variables - Instance, group, and project variable definitions (values are not imported). Masked, hidden, and file variables are marked secret
  • Runners - How many runners the instance has, and their tags

By default, projects in a user namespace, archived projects, projects with CI/CD turned off, and empty projects are skipped. The includes and components a pipeline uses are filled in by discovery after the import.

Each discovered include or component project appears under the group that owns it, including a project with no CI file and an archived project. A project in a subgroup appears under that subgroup, not under the groups above it. A project in a user namespace, or in a group the import did not include, appears under Not in a group. Placement uses the projects the latest import recorded, so import the source again if one still has no group.

Jenkins Import

Start a Jenkins import under Migration Assistant → Pipelines → Import → Jenkins. The importer extracts data directly from your Jenkins API.

What Gets Imported from Jenkins

  • 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

Organization Folders

Jenkins organization folders scan a GitHub organization, Gitea or Bitbucket owner, or GitLab group and generate a multibranch pipeline for each matching repository. The importer treats the organization folder as a folder and each generated pipeline as a child job.

For those jobs, and for any other multibranch project that uses a GitHub, Gitea, Bitbucket, or GitLab branch source, the importer fills in the repository name and clone URL from the branch source. Use that link when you map jobs to repositories.

Folder-Scoped Shared Libraries

In addition to global pipeline libraries, the importer reads libraries defined on a folder, an organization folder, or a multibranch project. Each library appears under the folder that defines it. Two folders can define a library with the same name and keep them separate.

Discovery resolves a job's library by name from the job's folder upward, and the nearest definition wins — including over a global library of the same name. An implicit library, which the folder loads for its jobs without an explicit load, applies only to jobs under that folder. A job outside the folder does not pick it up.

Uploading a JSON Export

On the Import from JSON card, Upload JSON opens the mapping wizard. It walks through repositories, credentials, plugins, building blocks, and jobs before anything is saved.

Dependencies in a JSON Upload

A JSON upload can declare which items depend on which others. Name each item by its external id — the id the export already uses for it — and list the external ids it depends on. The import records those as that item's dependencies, and the mapping wizard uses a job's dependencies on Building Blocks to pre-fill that job's Building Block mapping.

Include the declarations in any of these ways:

  • A file named dependencies.json
  • A dependencies field beside entities in the same file
  • A single declaration on its own

Declarations that name the same item are taken together and become that item's dependencies, replacing what it had. A declaration that lists nothing removes them. An item no declaration names keeps its dependencies. If the import replaces the items already imported from this source, the declarations are the whole set: an item it keeps has only the dependencies you declared for it, and an item you did not name has none.

An id that matches nothing

If any external id in an item's declarations is not an item of this source, none of that item's declarations are applied, and the import warns you, listing the item and the ids. The item keeps its current dependencies, so a typo does not clear them. If the import replaces the items already imported from this source, that item has none.

The Pipelines Dashboard

Migration Assistant → Pipelines opens on its Sources tab, an overview that groups all imported migration data by source system. Each source (Jenkins, Azure DevOps, GitLab) displays its instances with progress indicators and summary metrics, and a Mappings link to that source's Migration Mappings page.

Instance Summary Cards

Each instance shows:

  • Progress bar - the instance's items in the progress-bar buckets, from done to not started
  • Completion percentage - items that are migrated, done externally, or skipped count as complete
  • Metric columns - aligned counts for build units, extensions, reusable code, and credentials
  • Instance URL - normalized controller/organization URL for easy identification
The Sources tab of the Pipelines dashboard: summary tiles for 4 instances, 3,851 migration items and 47% complete, above the Jenkins section with two controllers, each showing its item count, a segmented progress bar with a legend, and counts of shared libraries, functions, plugins, and credentials.

A card marked some repositories only shows a discovery of some repositories, not the instance's whole analysis. See When a Discovery Read Only Some Repositories.

Scoped Instance Views

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.

The Jenkins · Production instance view: the Migration Items progress bar, Type, Status, and Batch filters with a search for payments/, and a table of payments jobs with their type, status, repository, and batch.

Within a scoped view you get:

  • Progress - the instance's jobs and reusable pipeline elements, as a segmented progress bar
  • Filter controls - Types, Statuses, and batch filters (Any batch, In a batch, or Not in a batch), and a search
  • The detail panel - click a row to open it, edit the item's repository and mapping, and click Migrate in Editor to migrate it on its own
  • Editor - once an item has a workspace, this column opens it

Filtering

The dashboard supports multi-select Types and Statuses filters so you can focus on a specific subset of migration entities — for example, viewing only Jenkins shared-library functions that are currently in progress. The Statuses filter groups each status under its progress-bar bucket.

The segmented progress bar at the top of each instance or batch is also 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.

Filter by Folder, Project, or Group

On a scoped instance view, the table adds a column named for that source's containers: Folder on Jenkins, Project on Azure DevOps, or Group on GitLab. Each row shows the container it sits in. A row nested several levels down shows the full path, such as DevOps / Docker Images. A row in no container shows a dash. The column is left out when nothing in the source sits in a container.

Open the filter in the column header to narrow the table to part of the source. Select a container, or several, and the table shows everything under each of them, including nested folders and subgroups. Uncheck a nested container to leave that part out and keep the rest of its parent. Where a container holds rows of its own beside nested containers, Directly in that container shows only those rows. Not in a folder, Not in a project, or Not in a group shows the rows that sit in none.

Search by name when the list is long, and expand a container to open what is under it. The selection stays in the URL, so you can reload or share the link and keep the same filter. If a link names a container the source no longer has, that selection is ignored and the table shows the whole source.

The progress bar still covers the whole source, not only the containers you picked.

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

Discovery parses the Groovy source of your Jenkins pipelines and shared libraries to extract structural facts, providing detailed insights into library usage patterns across your organization.

Automatic Discovery

Shared-library discovery runs automatically after Jenkins import and can analyze both repository-backed jobs and jobs with inline pipeline scripts.

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:

BadgeStatusDescription
Source missingRedThe pipeline's source file cannot be found
Pending scanYellowTemplate references an unprovisioned but known repository
Unknown repoGrayTemplate references a repository not in CodeCargo
The Azure DevOps instance table filtered to pipelines: sms-sdk-ci carries a red Source missing badge, tax-proxy-deploy-prod a yellow Pending scan badge, and feature-flags-ui-pr-check a gray Unknown repo badge with no repository.

Discovery runs automatically after import. To run it again, click Re-analyze at the top of the instance page, or Analyze for an instance that has not been analyzed yet.

Discovery Scope

Discovery resolves same-repository template chains completely and performs one hop of cross-repository resolution. Templates in unprovisioned repositories are flagged for future processing when those repositories are added to CodeCargo.

Discovery reads each YAML pipeline on the branch it builds from. Source missing means that file is not on that branch. Relative paths and @self includes are followed on that branch. A repository resource (@alias) is read as Repository Resources Pinned with ref: describes. A template used from one branch is tracked separately from the same file on another branch, and the pipeline's dependencies are only what its own branch reaches.

Each discovered template repository appears under the Azure DevOps project that owns it, including a repository with no pipeline of its own. A repository that no imported project contains, or that two projects list under the same name, appears under Not in a project. Placement uses the repositories the latest import recorded, so import the source again if a template repository still has no project.

When a Discovery Read Only Some Repositories

From an MCP client, you can limit an Azure DevOps discovery to some repositories: set repository_ids to them, or leave it out to cover every repository. You need the Migration Assistant manage permission. The instance card then marks the latest discovery some repositories only. That is those repositories' analysis, not the whole instance.

A discovery limited to repositories also reads the repositories that use their templates, and repositories waiting on their move. An instance that has never been discovered is always discovered whole.

Click Re-analyze to discover every repository of the instance. If a discovery of some repositories is still running, the whole-instance discovery waits until it ends, then runs. It does not join that discovery, and that discovery is not widened to cover the instance. Until the whole-instance discovery starts, the card still shows the one that read only some repositories.

If the instance is already running a discovery limited to other repositories, a limited request starts nothing there. Ask again once it ends.

Items You Have Already Worked On

When a discovery run finishes, it removes templates, plugins, and template repositories or libraries from an earlier analysis that nothing references any more. An import that removes items no longer in the source does the same. When discovery refreshes your GitHub Actions workflows, it removes a workflow it no longer finds: the file was removed, the repository was deactivated or moved to another organization, or the workflow became reusable.

An item stays if you have already worked on it:

  • You mapped it to a target. A suggestion with no target chosen does not count.
  • You added it to a batch, or to a wave you created.
  • You excluded it from a wave's dependencies.
  • You linked it to a workspace.
  • You set a status override on it.

A template that a kept item still includes stays too. An import run names the items it kept next to the ones it deleted.

A kept GitHub workflow leaves the GitHub estate wave CodeCargo maintains; a wave you created keeps it. A later refresh that finds it again marks it found and returns it to the estate wave with your work. Renaming a repository keeps its workflows, and the work on them, under the new name. A repository that takes a name another one gave up starts with none of that work, including when the original was deleted or moved to another organization. If you had worked on the earlier workflow, it stays, and discovery still does not find it.

No Longer Used

An item kept this way is marked No longer used wherever it is listed, in place of its discovery badge. On the instance page, N no longer used · Show them filters the table to those items.

Open the item. The detail panel shows No longer used with the date it was marked, and names the work that kept it, such as a mapping, a place in a batch or wave, a status you set, a workspace, or kept items under it. To finish with it, set up the same work on the item that replaced it, then click Remove, which deletes the item and that work. Remove is not offered while another item still sits under it. The mark clears when a later discovery or import finds the item again.

A GitHub workflow with this mark cannot be added to a batch or a wave. A batch that already holds one does not start or retry it, and items in the batch that depend on it wait until it is found again. See Items Marked No Longer Used. A Jenkins, Azure DevOps, or GitLab item with the mark can still be added, and a batch still runs it, because its source file may still be there.

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 (what a job relies on)

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 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 (what relies on a plugin)

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

Plugins are context, not migration units

Plugin entities are tracked in the dependency graph for impact analysis but are not migration units themselves. They never appear in the batch dependency advisory and cannot be added to a migration batch — only jobs and reusable pipeline elements are batch members.

Troubleshooting Imports

Connection failures

  • Verify the source URL and authentication credentials in your credentials file
  • Check network connectivity and firewall rules between the importer container and your source system
  • For Jenkins, ensure the Jenkins API is enabled and accessible; remember that localhost inside the container is not your host machine

Incomplete data import

  • Review the source-system permissions of the importing user — the importer can only see what that account can see
  • For Jenkins, check for plugin compatibility issues and verify Jenkins version compatibility

Next Step

With your data imported and discovery complete, continue to Mapping to configure how it translates to GitHub Actions.