How can we migrate Jira attachments across instances using REST API without plugins?

[Aruna Ramesh kumar]

Hi everyone,

I recently worked on a problem where we needed to migrate attachments across Jira instances.

Most available approaches depend on:
- Jira admins with elevated access
- External tools or paid plugins

I wanted to explore if this could be solved using only Jira’s REST APIs.

So I built a Java-based solution that:
- Migrates attachments from source to target issues
- Supports bulk migration using CSV (1000+ issues)
- Handles multiple attachments per issue
- Streams files directly without storing them locally

During implementation, I faced a few challenges:
- 403 authentication issues
- 303 redirect handling while downloading attachments
- Designing a streaming approach using InputStream / OutputStream

This helped me understand Jira beyond UI capabilities and approach it from an engineering perspective.

I’m curious to know:
Has anyone tried a similar approach for attachment migration?
Are there any best practices or limitations I should be aware of?

Happy to share more details if needed.

[Tomislav Tobijas]

Hi @Aruna Ramesh kumar ,

I can share two different approaches we used for different use cases:

1. Building custom local scripts - this one was similar to yours. This was used for migration from Azure Boards to Jira. We initially 'migrated' (read, imported) work items from Azure to Jira with CSV, and then created a script that migrated attachments
2. Forge app - this one uses a similar concept but just uses Forge. In particular, we've built synchronization between two cloud instances. I did build this with a couple of automation rules, but as these are fairly limited when it comes to attachments, my colleague built a Forge app to handle the attachments part.

All in all, there's no ideal out-of-the-box solution, so some form of customization is needed. ⚙️

Cheers,
Tobi

[Arkadiusz Wroblewski]

@Tomislav Tobijas 

Forge app are probably the closest option to a native solution.

This is one of those areas where I keep saying: it’s great to see AI solutions being added, but it would also be good to close at least some of the gaps where Data Center still has capabilities that Cloud is missing, and to take care of some basic use cases like this as well.

[Aruna Ramesh kumar]

Hi @Tomislav Tobijas , thanks for sharing these approaches — really helpful breakdown!

I explored a similar custom script-based approach for cross-instance migration, especially for one-time or controlled bulk use cases. In my scenario, attachments weren’t directly accessible externally, so I used Jira REST APIs to fetch and stream them securely from the source instance and upload to the target.

I agree with your point — there’s no ideal out-of-the-box solution yet, and some level of customization is almost always needed depending on the use case.

Forge definitely looks like the closest native approach for ongoing synchronization. But for bulk migrations, I found script-based solutions to be simpler and more flexible to control.

Sharing my implementation here in case it’s useful:
👉 [GitHub - arunaramesh133-lang/jira-cross-instance-attachment-migrator: Migrate Jira attachments acro…]

Would be interested to hear your thoughts on handling large-scale migrations or any best practices you’ve seen in production scenarios.

[Tomislav Tobijas]

Thanks for sharing the repo @Aruna Ramesh kumar ! 🙏

Would be interested to hear your thoughts on handling large-scale migrations or any best practices you’ve seen in production scenarios.

Can't say there are any specifics when it comes to that. Only that you should review the initial requirement and scenario/use case as much as possible. Break it down into details to see what you need to do and then decide on the approach. For example, what data needs to be migrated, how will you validate the migration, etc.

📊 When it comes to validation, make sure you prepare some metrics or dashboards that will help when reviewing the completeness of it (even though, when it comes to CSV import, you get that report at the end of the import process).

Lastly - test, test, and do more tests 😅 Despite doing a lot of them, we did have a couple of cases where clients said they've checked out everything, only that in production migration, it seems they've forgotten something, so we had to import specific subsets of data (bulk edit in fact).

[Aruna Ramesh kumar]

Thanks a lot for the insights @Tomislav Tobijas really appreciate it 🙏

I completely agree that in large-scale migrations, the real complexity lies more in defining the scope and validation strategy than in the actual implementation. One thing I’ve been focusing on is keeping the approach controlled and incremental — using CSV-driven mappings to avoid “all-at-once” migrations and instead handle data in well-defined subsets.

On validation, beyond basic source vs target comparisons, I’m exploring more granular checks — for example, verifying attachment counts and link consistency at an issue level, and identifying mismatches rather than relying solely on import-level reports. This becomes especially important when dealing with partial migrations or re-runs.

The testing aspect is something I’ve already experienced firsthand 🙂 — small batches tend to behave very differently from bulk runs. Because of that, I’ve been designing the scripts to be repeatable and safe to re-run, so that missed or inconsistent data can be corrected without redoing the entire migration.

Would be really interested to hear how you typically approach validation at scale in production — especially when dealing with edge cases that aren’t visible in standard reports.

[Arkadiusz Wroblewski]

Hello @Aruna Ramesh kumar 

Nice work building this, the streaming approach is the right call for bulk migrations, avoids disk I/O issues and keeps memory usage predictable.

A couple of things worth watching out for at scale:

The `X-Atlassian-Token: no-check` header is required when POSTing attachments to the target instance. Without it you'll get a 403 even with valid credentials, it's easy to miss since it's not always obvious from the error.

At 1000+ issues, API rate limiting on the target instance can become a real bottleneck. Worth building in retry logic with exponential backoff if you haven't already.

Also worth checking the attachment size limit on the target instance upfront. If the target has a lower limit than the source, those uploads will fail silently unless you're explicitly handling the response codes.

Would love to see the code if you're planning to share it, this kind of solution comes up regularly and would be useful for the community.

[Aruna Ramesh kumar]

Hi @Arkadiusz Wroblewski , thanks a lot for the feedback — really appreciate it!

You're absolutely right about the X-Atlassian-Token: no-check header. I initially ran into 403 errors during upload and later realized this header is required when POSTing attachments. I've now incorporated it into the upload logic.

I also agree on the rate limiting concern. For larger datasets (1000+ issues), I’ve started adding retry logic with basic backoff handling, and I’m planning to improve it further with exponential backoff and better throttling.

Regarding attachment size limits, that’s a great point. I’m now validating responses more explicitly to catch such failures instead of assuming successful uploads.

As suggested, I’ve made the solution available here:
👉 [GitHub - arunaramesh133-lang/jira-cross-instance-attachment-migrator: Migrate Jira attachments acro…]

It supports:

• CSV-based bulk migration
• Streaming attachments without local storage
• Handling multiple attachments per issue

Would love any further suggestions or improvements from the community!

Thanks again for your valuable inputs 🙌

[Aruna Ramesh kumar]

Just to add a quick clarification - this approach doesn’t require admin-level access.

It works with standard user permissions, as long as the user has:

- Access to view source issues and attachments
- Permission to add attachments in the target project

So it can be executed using a regular API token with appropriate project-level permissions.

[Aruna Ramesh kumar]

---

Hi all, thanks for sharing these approaches — very insightful!

I explored a similar custom script-based approach, especially for cases where a lightweight, controllable solution is needed without relying on Forge or plugins.

In my case, I built a Java-based solution using Jira REST APIs that:

• Migrates attachments across instances using CSV-based issue mapping
• Streams attachments directly (avoiding local storage)
• Handles multiple attachments per issue

One of the key challenges I faced was handling authentication nuances (like X-Atlassian-Token) and download redirects, but it worked reliably once addressed.

I agree that Forge is probably the closest native option, but for one-time migrations or controlled bulk operations, a script-based approach can be simpler and more flexible.

Sharing the implementation here in case it helps others:
👉 GitHub - arunaramesh133-lang/jira-cross-instance-attachment-migrator: Migrate Jira attachments acro…

Would be great to hear thoughts or suggestions!

[Mohamed Benziane]

Hi,

When I needed to migrate attachments, I just used a CSV import : How to migrate issues with attachments using the CSV import in Jira Server and Data Center | Jira and Jira Service Management | Atlassian Support

I can confirm that it's working fine for Jira Cloud too. You just need to be sure that the url of the attachments is reachable by your target instance.

[Aruna Ramesh kumar]

Hi @Mohamed Benziane , thanks for sharing this approach!

Yes, CSV import with attachment URLs works well when the attachments are already accessible via public or reachable URLs.

In my case, the challenge was slightly different — the attachments were stored within a source Jira instance and not directly accessible externally. So I explored a REST API-based approach to:

• Fetch attachments securely from the source instance
• Stream them directly
• Upload them to the target instance

This helped in scenarios where:

• Attachments are not publicly reachable
• Controlled migration is required across instances
• We want to avoid exposing attachment URLs externally

So I see both approaches as useful depending on the use case 👍

I’ve shared the implementation here in case it helps:
👉 [GitHub - arunaramesh133-lang/jira-cross-instance-attachment-migrator: Migrate Jira attachments acro…]

Would be interested to hear if you’ve handled similar restricted-access scenarios!