Mapping

The Mapping Wizard

After importing your data, the mapping wizard guides you through configuring how your legacy CI/CD data translates to GitHub Actions. The wizard follows a structured workflow:

1. Upload - Import data from your legacy CI/CD system (or continue from an importer run)
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. Nothing is committed until you confirm.

You can also revisit and edit mappings after the wizard completes — inline from the dashboard's scoped entity tables, or in bulk on the Migration Mappings page.

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

Reusable Building Blocks

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.

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 (Jenkins credentials, Azure DevOps service connections) 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

Remember that credential values are never imported — mapping defines where each credential should live in GitHub, and you recreate the secret values there yourself.

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

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.

Exporting and Importing Mappings

The Migration Mappings page includes Export and Import actions in its header. Use them to carry mappings out of a sandbox organization and bring them back into your real target organization, or to hand the mapping work to a teammate who fills it in using Excel.

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.

Mappings that target multiple Building Blocks include a Primary/Additional role column so you can tell which row drives the mapping.

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:

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. Building Block references are matched by repository and path rather than by internal ID, so a workbook exported from a sandbox organization can be imported into a different organization that shares the same source instance.

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.