---
title: Understand the migration tool repository
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

## Understand the migration tool repository

The [Kentico Migration Tool](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool) repository contains multiple projects. For customization work, you'll interact primarily with:

- **Migration.Tool.CLI/** - to [configure the tool](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.CLI/README.md#configuration) in `appsettings.json` and run the command-line executable
- **Migration.Tool.Extensions/** - to implement customization related to any content remodelling (e.g., mapping classes, transforming widgets, extracting reusable field schemas)
- **Migration.Tool.KX13.Extensions** or **Migration.Tool.KX13.NET48.Extensions** - to copy controllers from when configuring the Page Builder content migrations

The remaining projects (Core.KX13, KXP.Api, Common, etc.) provide either shared or version-specific migration logic that runs automatically. Generally, you don't need to modify these, with the exceptions of specific advanced scenarios (e.g., a custom command handler), and contributions to the tool's development (features/bug fixes).

> **Tip:** See the complete repository structure guide [in the GitHub documentation](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/docs/Repository-Structure.md).

## Use a three-repository approach

For data migration you need:

1. Your source instance
2. Your target Xperience by Kentico instance
3. A copy of the Kentico Migration Tool

We recommend you **use a three-repository approach** for upgrade projects with a clone of the migration tool repo **per project**.

```text title="Example repository structure"
Your-Upgrade-Reporitory/
├── kx13-source/              # 1. Source KX13 instance
│   └── (existing KX13 code - largely unchanged)
├── xbyk-target/              # 2. Target XbyK instance  
│   └── (new XbyK code - evolves iteratively)
└── migration-tool-custom/    # 3. Kentico Migration Tool (+ customizations)
    ├── Migration.Tool.CLI/
    │   └── appsettings.json
    ├── Migration.Tool.Extensions/
    │   ├── ClassMappings/
    │   ├── CommunityMigrations/
    │   └── WidgetMigrations/
    └── docs/
        ├── decisions.md
        └── scenarios.md
```

**Why a copy of the migration tool per project?**\
Each project needs unique migration tool customizations. Isolating the tool enables:

- Version control for migration logic
- Team collaboration on configurations
- Records of migration decisions
- Reusable patterns across migration runs

> **Tip:** [Git submodules](https://www.atlassian.com/git/tutorials/git-submodule) let you include one Git repository as a subdirectory of another, so you can work with all three repositories (source, target, migration tool) from a single parent repository while tracking each independently.