Attachments & Comments

Attachments

Attachments are migrated after all work items are created. Migrayt downloads each attachment from ADO using the work item's AttachedFile relations and re-uploads them to the corresponding Jira issue.

Limits and constraints

Inline image handling

ADO descriptions often contain <img> tags pointing to ADO attachment URLs (e.g. images embedded directly in the item description). After uploading all attachments, Migrayt rewrites these URLs in the Jira description to point to the newly uploaded Jira attachment URLs.

Without this step, embedded images would still point to ADO and would break once ADO access is revoked.

What happens to attachments if the file fails to upload

If an individual attachment upload fails (e.g. due to a network timeout), Migrayt logs the failure and continues. The work item is still migrated without that attachment. Failed attachments are listed in the post-migration report so you can upload them manually if needed.

Comments

Comments are migrated after work items are created, in chronological order (oldest first) to preserve the conversation timeline.

Attribution header

Because Migrayt uses a single service account to write to Jira, all comments are created under that account. To preserve the original author and date, each comment receives an attribution header:

[Migrated from ADO — alice@company.com on 2024-03-15]

[Original comment text follows]

The header is rendered in italic in Jira using Atlassian Document Format. The original comment body follows immediately.

HTML comment content

ADO comments are stored as HTML. Migrayt converts them to ADF using the same HTML-to-ADF conversion used for item descriptions. See Field Mapping — Description Conversion for the supported HTML constructs.

Comment ordering

Comments are written to Jira in the exact order they appear in ADO (createdDate ascending). If you have comments from multiple authors interleaved across a long thread, the order is preserved.

Comment counts

ADO's System.CommentCount field is used to determine which items have comments. Only items with CommentCount > 0 have their comments fetched from the ADO Comments API, which avoids unnecessary API calls for the majority of items.

Example migration output

For an ADO work item with 3 attachments and 2 comments:

ADO Work Item #10432
├── Jira Issue: PROJ-142 (created)
├── Attachment: requirements.pdf (1.2 MB) → uploaded ✓
├── Attachment: mockup.png (340 KB) → uploaded ✓; inline URL rewritten in description ✓
├── Attachment: archive.zip (180 MB) → uploaded ✓
└── Comments:
    ├── [2024-01-10] alice@co.com: "Initial spec complete"   → created ✓
    └── [2024-01-15] bob@co.com: "Reviewed, needs revision" → created ✓