nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

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.

Accepted answers

All comments

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.

Tomislav Tobijas

Hi @Aruna Ramesh kumar ,

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

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
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.

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 @Arkadiusz Wroblewski , thanks a lot for the feedback — really appreciate it!

You're absolutely right about the <strong>X-Atlassian-Token: no-check</strong> 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

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!

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.

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!

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.

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).

Dr_ Ankita Mehta-OpsHub_ Inc

Hi @Aruna Ramesh kumar

Interesting approach, and yes, it’s definitely possible to migrate attachments using Jira REST APIs like you’ve done. A few points to be considered:

Your approach is valid but limited at scale: REST APIs can handle attachment migration, but bulk scenarios like 1000+ issues often run into rate limits, retries, and performance bottlenecks.
Redirects and auth are expected hurdles: The 303 redirect and 403 issues you faced are common, especially with attachment storage and permission scopes. Your handling with streaming is the right direction.
Metadata gaps: APIs don’t always preserve original author, timestamps, or full context of attachments, which can matter later for audits or traceability.
Error handling and retries: With large datasets, partial failures are inevitable, so maintaining consistency across source and target becomes tricky.

It might be worth taking a look at OpsHub Migration Manager (listing on Atlassian marketplace) in your case, if this is more than a one-off script. It supports phased or full migrations with no downtime or disruption, and ensures attachments, comments, and relationships are preserved with full historical fidelity.

Hope it helps!

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

jira

cloud

migration

rest-api

api

jira-cloud

attachment

automation