Migration Guides
Your First Migration

Running Your First Migration

This guide walks through every screen of the Migrayt wizard in detail. If you want a quick summary, see the Quick Start instead.

Before You Begin

Have these ready:

  • Your ADO organisation name and project name
  • Your Jira Cloud site URL and project key
  • A Jira account with Project Administrator role on the destination project

The Wizard Steps

Step 1 — Connect Platforms

You'll see two cards: Source (Azure DevOps) and Destination (Jira Cloud).

Connecting ADO:

Click Connect with Microsoft account to authenticate using OAuth (no PAT required). Migrayt will show you your accessible ADO organisations. Select the correct one.

Alternatively, click "Use PAT instead" and enter a Personal Access Token. The minimum required scopes are: Work Items (Read), Project and Team (Read), Analytics (Read).

Then enter your Project Name exactly as it appears in ADO.

Connecting Jira:

Click Connect with Atlassian account to authenticate via OAuth. Select your Jira Cloud site and choose the destination project from the dropdown.

You'll also be asked to select a Jira board for sprint mapping. Choose the Scrum board you want ADO iteration paths mapped to. If you have a Kanban board, see Iteration & Sprint Mapping.

Both connections are verified before you can proceed. You'll see a green "Connection verified" indicator.

Step 2 — Configure Scope

This screen lets you filter the migration:

  • Area filter — Restrict to a specific area path subtree (e.g. MyProject\Backend)
  • Type filter — Restrict to specific work item types (e.g. only User Stories and Bugs)
  • Dry run mode — Enable to preview transformation without writing to Jira (free)
  • Migration options — Toggle attachments, comments, and links on/off

For your first migration, leave all options at their defaults and proceed.

Step 3 — Map Fields

This screen shows the type and field mappings generated by AI. Work through each section:

Work Item Types tab: Review the type mapping table. High-confidence suggestions are pre-ticked in green. Review amber (medium confidence) and red (low confidence) mappings carefully. Adjust any that don't match your intent.

If you have the Feature → Epic hierarchy problem, you'll see a prompt here. Choose Option A (collapse), B (flatten), or C (manual).

Fields tab (per type pair): For each type pair (e.g. ADO User Story → Jira Story), review the field mappings. Custom fields that could not be mapped are listed at the bottom in the "Unmapped Fields" section.

Iterations tab: Review the sprint mapping suggestions. Each ADO iteration path is shown with the suggested action (map to existing, create new, or drop). Adjust as needed.

Areas tab: Review the component mapping suggestions. Each ADO area path node is shown with the suggested action. Adjust the mapping for any nodes that should resolve to a different component.

When all four tabs are reviewed, click Continue.

Step 4 — Preview Migration

This screen shows the dry run output before you confirm.

Review the transformed sample items carefully. Pay attention to:

  • Description rendering (especially if you have complex HTML)
  • Custom field values
  • Sprint and component assignments
  • User assignments (check for "ghost" assignments)

If everything looks correct, click Confirm & Proceed.

If anything needs adjustment, click the back arrow to return to the mapping screen.

Step 5 — Pricing & Payment

The price is calculated from your scan results. Review the breakdown:

Work items:    5,847 × £0.012 = £70.16
Attachments:   4.2 GB × £0.50 =  £2.10
Subtotal:                        £72.26
Minimum price:                   £99.00 (applied)

Volume discount (< 10k items):   5% off
Final price:                      £94.05

Click Pay with Stripe to complete payment. Stripe Checkout opens in a new tab or overlay. After payment, you are returned to Migrayt and the migration is enabled.

Step 6 — Migration Execution

Click Start Migration. The progress screen shows:

  • A live counter of items migrated / total
  • Current phase and operation
  • Speed in items per minute
  • Estimated time remaining
  • The live log of each item being processed

You can close the browser tab at any point. The migration continues in the background. Return to the migration URL to reconnect to the live stream.

When complete, you'll see the migration report automatically. It's also sent to your registered email address.

After Migration

  1. Log in to Jira and verify your items
  2. Check the post-migration report for any items that need attention
  3. Review ghost-assigned items and reassign them
  4. Notify your team that Jira is ready

If anything doesn't look right, see Understanding Your Report or contact support@migrayt.ai.

Pre-Migration ChecklistDry Run