Migration
Mapping
The Migration Mappings Page
After importing your data, you decide how each legacy item translates to GitHub Actions on the Migration Mappings page. Open it with Migration Mappings on the Pipelines dashboard, or with Mappings in a source's section on the Sources tab. Each source has its own page.
The page has a tab for repositories and one for each kind of item, named in the source's own vocabulary:
| Tab | Jenkins | Azure DevOps | GitLab |
|---|---|---|---|
| Repositories | Repositories | Repositories | Repositories |
| Jobs | Jobs | Pipelines | Pipelines |
| Reusable pipelines | Shared Libraries | Template Repositories | Component Projects |
| Credentials | Credentials | Service Connections | CI/CD Variables |
| Plugins | Plugins | Tasks | Built-in Templates |
Each row maps one item to a Target type and a target. Edits stay on the page until you click Save. Export and Import in the header move mappings in and out as a spreadsheet; see Exporting and Importing Mappings.
| Tab | Target types |
|---|---|
| Jobs | Building Block Workflow, Reusable Workflow, Custom instructions |
| Reusable pipelines | Building Block Action, Building Block Workflow, Custom instructions |
| Credentials | GitHub Secret, GitHub Variable, Custom instructions |
| Plugins | GitHub Action, Reusable Workflow, Building Block Action, Building Block Workflow, Custom instructions |
Every tab also offers Not Mapped. Custom instructions gives the migration agent notes to follow instead of a GitHub target.
You can also edit one item's repository and mapping in its detail panel on the Pipelines dashboard. Pipeline sync and the importer save their data directly, with the default credential mappings described under Credential Mappings. A JSON upload goes through the mapping wizard first.
Patterns that recur across jobs, and the Building Block Blueprints they need, are reviewed later, in a Pipelines wave.
Repository Mapping
The Repositories tab assigns each imported job and reusable pipeline to a CodeCargo repository. Each row shows the item's Git URL from the source, to help you pick. Choose Unmapped to postpone the decision.
To map many items at once, export the mappings, fill in the Repositories sheet, and import it — see Exporting and Importing Mappings.
Pipelines whose repositories were migrated to GitHub with GitHub Enterprise Importer are linked automatically. See Repository Link Resolution.
Job Mappings
A job mapped on the Jobs tab is converted onto that target: its workflow, written in the job's own repository, calls the building block or reusable workflow.
- Building Block Workflow - Pick a block under Existing building blocks, or one under Planned in this migration: a block that a saved mapping on the Reusable pipelines tab will create. With neither, the field reads No building blocks available - map a Reusable Pipeline to a Building Block first.
- Reusable Workflow - Create new names the path under
.github/workflows/where the migration writes it. Use existing names the repository and path of a workflow that already exists. Typeowner/repofor one in another organization. - Custom instructions - Notes the migration agent follows for this job.
See A Job Mapped to a Building Block for how the batch runs it.
Reusable Pipeline Mappings
A reusable pipeline element — a Jenkins shared-library function, an Azure DevOps template, or a GitLab include — is mapped on the Reusable pipelines tab to the building block it becomes.
- Building Block Action or Building Block Workflow with Create new - Pick the destination repository, an existing repository in your organization, and the block's path: a workflow file under
.github/workflows/, or an action name, which is saved as.github/actions/<name>/action.yml. The migration creates the block there. - Building Block Action or Building Block Workflow with Use existing - Pick a building block that already exists, or, for a workflow, one planned in this migration.
- Custom instructions - Notes the migration agent follows for this element.
An element with no mapping has no destination for its output, so its migration pauses to ask. See No Destination Mapping.
On Jenkins, Add function adds a shared-library function the import did not list. Give it a name and a library, and optionally its source path, which defaults to vars/<name>.groovy. Deleting a function deletes the item and its mapping. A job mapping that targets it keeps its target, but that target does not resolve until you pick again on the Jobs tab.
Additional Building Blocks
A job, reusable pipeline element, or plugin can use more building blocks than its target. Click the row's building blocks chip, which reads +N once it has some, to see what it Also uses, and click Add to add another. Click Save to keep the change. A row with no target drops its additional blocks when you save it.
Credentials have no additional blocks. An export lists additional blocks as their own rows; see Exporting.
Credential Mappings
Map source credentials (Jenkins credentials, Azure DevOps service connections and variable-group keys, and GitLab CI/CD variables) to a GitHub Secret or a GitHub Variable, or give the migration agent Custom instructions for one:
- GitHub Secret - Map the credential to a GitHub Actions secret name. The converted workflow reads it as
${{ secrets.NAME }}. - GitHub Variable - Map a non-secret value to a GitHub Actions variable name, read as
${{ vars.NAME }}. Offered only for credentials, in the import wizard, on the Migration Mappings page, and when you edit that credential's mapping. - Custom instructions - Tell the migration agent how to handle a credential that needs special handling. The agent follows your notes during the migration.
Every Azure DevOps import maps a non-secret variable-group key that has no mapping to a GitHub Variable named after it. A character GitHub does not allow in a variable name becomes _. Secret keys, Key Vault keys, and names starting with a digit or GITHUB_ stay Not Mapped. A key you already mapped keeps its mapping.
Every GitLab import maps a CI/CD variable that has no mapping. A masked, hidden, or file variable becomes a GitHub Secret named after its key. A plain variable becomes a GitHub Variable named after it. A character GitHub does not allow in a name becomes _. A name that starts with a digit or GITHUB_ stays Not Mapped. So do keys that differ only by case, because GitHub's names ignore case, and the import says so. A variable you already mapped keeps its mapping. The same key in more than one environment is one name, and each environment keeps its own value.
Credential values are never imported. Add the secret or variable in GitHub under the name you mapped, and recreate the value there yourself.
GitHub variables are not encrypted
The import wizard and that credential's mapping warn you when the source marks the value secret — every Jenkins credential, and an Azure DevOps value flagged secret. On the Migration Mappings page that warning appears for Jenkins credentials. Prefer GitHub Secret for those values.
GitLab Variables with No Mapping
GitLab sets project, group, and instance CI/CD variables in the job's environment, so the pipeline file does not have to name them. When you convert the job, a variable you mapped is read from that secret or variable. Values are never written into the workflow.
An import maps most GitLab variables (see above). One with no mapping is read under its own key: ${{ secrets.KEY }} when it is secret, and ${{ vars.KEY }} when it is plain. The migration reports each one so you can create it in GitHub. A name GitHub will not accept — one that starts with a digit or GITHUB_, or a key that differs from another only by case — is stored under a valid name. The workflow passes it to the step under its original key, and the migration reports the new name.
A group or instance variable reaches the conversion only when the project's own CI file reads it. One used only in an included file or by a tool is not listed, so the migration reports one it suspects the job needs.
If the project's CI/CD variables could not be read, the migration asks which ones the project sets. It does not assume the project has none.
Plugin Mappings
Map source plugins or tasks to what the converted workflow uses in their place: a GitHub Action such as owner/action@v1, a Reusable Workflow by its repository and path, a Building Block Action or Building Block Workflow that already exists, or Custom instructions. A plugin always references something that exists. Its mapping never creates one.
The "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.
A GitLab CI/CD variable set to "Not Mapped" is still passed to the converted job under its own key; see GitLab Variables with No Mapping. The next import maps it again by the default rule, as an Azure DevOps import does for a non-secret variable-group key.
Exporting and Importing Mappings
The Migration Mappings page includes Export and Import actions in its header. Use them to hand the mapping work to a teammate who fills it in using Excel, or to carry mappings to another organization that imports the same source instance.
In a Migration Plan
Map credentials in the plan's sandbox. The plan copies the sandbox's pipeline import, including credential mappings, into each destination org, so you don't export mappings from the sandbox and import them there. See Set Up the Conversion.
Exporting
Click Export to choose between:
- Excel workbook (.xlsx) - A single file with one sheet per category, dropdown validation for target type, mode, and repository, and a "Read me" legend sheet. Every discovered entity is included, so the workbook doubles as a fill-in worksheet even for mappings you haven't configured yet.
- CSV, one sheet - A separate CSV download per category (plus a repositories CSV) for lightweight editing or scripting.
A mapping with additional building blocks has a Mapping role column: Primary is the item’s main mapping, one per item, and each Additional row attaches an extra building block to the same item.
The credentials sheet has a Variable name column beside Secret name. For a GitHub Variable, enter the name under Variable name. Secret name applies only when Target type is GitHub Secret. GitHub Variable is not valid on the other sheets. If the file has no Variable name column, the name is read from Target identifier, including a credentials sheet whose name column is headed Secret name.
Importing
Click Import to open a dialog where you drop in an exported workbook or CSV. Before anything is applied, CodeCargo shows a classified preview of every row:
| Classification | Meaning |
|---|---|
| New | No mapping exists yet for this entity |
| Updated | The target differs from the current mapping |
| Unchanged | The target matches what's already saved |
| Cleared | A Repositories row set to Unmapped clears the item's repository |
| No target | The row has no target specified |
| Not found | The entity couldn't be matched in this org |
| Invalid | The row failed validation |
Each row that needs attention shows a specific reason. Import never deletes a mapping — blanking out a target in the file simply results in no change for that row. The one exception is the Repositories sheet, where Unmapped clears an item's repository. Building Block references are matched by repository and path rather than by internal ID, so a workbook exported from one organization can be imported into another that shares the same source instance.
Review before applying
The import preview is non-destructive — nothing is saved until you confirm. Use the preview to catch unmatched or invalid rows before applying the file.
The Mapping Wizard
A JSON upload under Migration Assistant → Pipelines → Import → JSON opens Import from JSON, a wizard that maps the upload before anything is saved:
- Upload - Upload the migration export
- Review - Examine the imported item counts and choose how the import treats existing data
- Repository Mapping - Match legacy jobs to GitHub repositories
- Credential Mappings - Map legacy credentials to GitHub secrets or variables
- Plugin Mappings - Map legacy plugins to GitHub Actions
- Reusable Building Blocks - Map shared-library functions and templates to Building Blocks
- Job Mappings - Assign jobs to Building Blocks or reusable workflows
- Confirm - Review summary and complete the import
Each step offers the same target types as the matching tab. Repository Mapping suggests a repository for each job by matching its name against your repositories, and filters to rows that still need review or are ready to import.
The confirmation step shows at-a-glance summary cards with net changes, configured mappings, and jobs ready for migration. Nothing is committed until you confirm. Afterwards, Configure Mappings opens the Migration Mappings page, where you can change any mapping.
Troubleshooting Mappings
Repository matching failures
- Use manual repository selection for complex job names
- Check GitHub App permissions for repository access — see GitHub Integration
- Verify repository names and organization settings
Plugin mapping gaps
- Create custom mappings for organization-specific plugins
- Consult the GitHub Actions marketplace for equivalent actions
- Consider workflow redesign for deprecated Jenkins plugins
Next Step
With mappings configured, continue to Migrating Jobs to convert them with AI assistance.
