Migrating your issue tracker in a week

Tracker migrations fail for the same reason data migrations fail: somebody promises to bring everything across, and then spends four weeks discovering what everything means.

Introduction

Decide what you are not migrating before you decide anything else. Closed issues older than a year, abandoned projects and the eight custom fields nobody has filled in since 2024 can be archived rather than translated.

What remains is usually small enough to move in an afternoon. The week goes on agreeing states, owners and priorities — the things that were never written down in the old tool either.

Run both systems for exactly one sprint. Any longer and people learn to live with two sources of truth, which is worse than either tool on its own.

Map states before you map anything else. Most teams find they have three real states wearing seven different names, and collapsing them is the single largest quality-of-life win of the whole exercise.

Keep identifiers stable where you can. Links in old pull requests, incident reports and customer emails will outlive the migration, and a redirect costs an hour to set up.

Software and tools

Export to a flat file first, even if the destination has a direct importer. A CSV you can read is the only way to catch the fields that silently did not come across.

Automate the import, then run it three times into a throwaway workspace. The third run is the one where you notice the attachments are missing.

Other resources

If you are planning a move, three decisions carry most of the risk:

1. What are you deliberately leaving behind?
2. Who owns the mapping when two people disagree about a state?
3. When exactly does the old tool become read-only?

The tool you land on matters less than the agreement you write on the way there. Most teams get a better process out of the migration than they get out of the software.

Set the read-only date first and work backwards from it.