Migrate

Move projects, issues, comments, attachments, and time history from Jira, Linear, Azure DevOps, Zendesk, or Countersoft Gemini into Ekso — in two commands.

What ekso migrate is

ekso migrate is a built-in importer that moves projects, work items, comments, attachments, links, and time history from another platform into your Ekso tenant. One source picker, one set of commands, one cache format.

It currently supports five sources — and for Jira, all three editions (Cloud, Data Center, and Server) are supported and auto-detected:

Source	Branch	Read
Atlassian Jira	ekso migrate jira	Migrate from Jira
Linear	ekso migrate linear	Migrate from Linear
Azure DevOps	ekso migrate devops	Migrate from Azure DevOps
Zendesk	ekso migrate zendesk	Migrate from Zendesk
Countersoft Gemini	ekso migrate gemini	Migrate from Gemini

Every source uses the same workflow, the same flag surface, and the same destination shape on the Ekso side. Once you’ve migrated one source, you’ve migrated them all.

Two phases — collect and apply

The migrator splits cleanly into two commands:

ekso migrate <source> collect ...   # source platform → local SQLite cache
ekso migrate <source> apply   ...   # local SQLite cache → Ekso REST

Splitting the work is deliberate:

• A 50,000-issue Jira collect can take an hour. A network blip during apply must not force re-fetching from the source.
• apply --dry-run walks the cache and tells you exactly what would be created — no Ekso writes — before you commit.
• apply is resumable. Every successful create writes the source-id → Ekso-id pair into a local IdMap table; a re-run skips already-applied rows.
• The two phases can run on different machines. Collect on a workstation that can reach the source platform; copy the SQLite file; apply from a CI runner with Ekso credentials. This is the on-prem migration story.

The cache lives at ~/.ekso/migrate/<source>-<timestamp>.sqlite by default. Override with --working-dir.

What you get on the Ekso side

The migrator preserves authoring fidelity. Every comment, every worklog, every attachment is attributed to the user who created it on the source platform — not to the running CLI user.

Source concept	Ekso shape
Project	DataContainer
Issue / Ticket / Work Item	DataItem
Comment / Discussion	DataAnnotation
Attachment	DataFile (multipart upload)
Worklog / Time entry	DataItem.Time[] (in the same item POST)
Sprint / Cycle / Iteration / Version	DataCycle
Component / Area / Group / Tag	ConfigLabel + DataItem.Tags
User / Agent / Identity	DataUser (matched by email or minted)
Issue link / Subtask	DataLink
Custom field	DataItem.Field[] (via field-map) or Meta (lossless)

The mapping is the same across sources. Differences are in the source-specific quirks (Jira’s date format, Linear’s cursor pagination, Zendesk’s first-comment-as-description, DevOps’ WIQL chunking, Gemini’s dual-mode dispatch) — see the per-source pages.

Every imported DataItem carries a custom field called ImportSource that retains the original source key (e.g. ENG-123 for Linear, ACME-42 for Jira). The field is auto-created on the destination process if missing. Hide it on the process if it’s noise — the value stays on every item either way and gives you a back-reference for support, audits, and re-runs.

Identity resolution — three strategies

External platforms attribute every comment, worklog, and item to a user. Ekso has to record those authors faithfully or the audit trail breaks. The CLI offers three strategies via --user-strategy:

Strategy	What it does
match-or-create (default)	Match each source user by email; if no Ekso user has that email, mint one (random password, no invite email sent).
match-only	Match by email only. Source users with no Ekso match fall back to --fallback-user (or the running CLI user).
migration-bot	Force every author to a single fallback user. Lossy, but simple if author fidelity isn’t important.

The default mints users without sending an invite email so production users don’t get a flood of “Welcome to Ekso” emails the day before a migration. See Identity resolution for the full mechanics and post-migration cleanup.

What does not migrate

Honest list:

• Workflow definitions / state machines. The migrator snapshots the current state of each item. State-transition rules and screen layouts on the source platform don’t transfer — the customer’s destination process defines the new shape.
• Permissions / role assignments. Source-platform ACLs don’t map. Configure access on Ekso’s side after the migration.
• Brand customisations. Themes, logos, custom domains are platform-specific.
• Source-platform automations (Jira automations, DevOps build pipelines, Zendesk macros, Gemini rules). Re-author them as Ekso rules.
• Reverse migration. This is one-way — Ekso → source is not supported.
• Ongoing sync. This is a one-shot migration tool, not an integration.

Each per-source page calls out additional source-specific gaps.

Before you run anything

Read Before you start — prerequisites, secrets policy, token rotation. Then pick your source.

Where to next

• Before you start — prerequisites and the secrets policy.
• Command reference — collect, apply, list-*, status, every flag.
• Identity resolution — match-or-create, match-only, migration-bot.
• Field mapping — migration.fields.yaml format and worked examples.
• Troubleshooting — exit codes and per-source error patterns.