Atlassian Forge provides managed storage for applications built on Jira and Confluence. As organizations expand into different regions, they may need to move application data to meet data residency requirements, improve regional alignment, or satisfy internal compliance policies.
For developers, this raises an important question: how can a Forge application continue to behave correctly when its storage location changes?
Unlike a traditional application hosted on a virtual machine or cloud database, Forge uses Atlassian-managed infrastructure. Developers do not directly select a storage region for every database operation. Instead, Forge supports data residency by aligning its hosted storage with the location selected by the administrator of the Atlassian product.
The migration process also affects application execution. Forge functions and UI extensions may temporarily become unavailable while the migration takes place, and product events are queued for processing afterward.
Therefore, the goal is not to manually move storage while guaranteeing uninterrupted Forge app execution. It is to design the application so that Atlassian can migrate the hosted data without requiring developers to perform a separate database migration or lose queued product events.
This article explains how Forge data residency works, what happens during a regional migration, how to prepare an application, and how to handle events and external storage safely.
Understanding Data Residency in Atlassian Forge
Data residency determines the geographic location where an organization's application data is stored.
For example, an organization operating in India may require its in-scope application data to remain in the India region. Another organization may select Germany, Australia, Canada, or the United States based on its business and regulatory requirements.
Atlassian provides data residency support for Forge applications using persistent hosted storage.
The supported storage capabilities include:
- Key-Value Store (KVS).
- Custom Entity Store.
- Forge SQL.
- Forge Object Store.
When an organization administrator moves Jira or Confluence data to another supported location, Forge-hosted application data moves along with the associated Atlassian product.
This means developers do not need to export and import their hosted storage records manually for a standard regional data residency migration.
For example, if a Jira site moves from the Global location to India, eligible Forge applications using persistent hosted storage are also moved to the India location.
One important detail is that India is not automatically selected simply because an organization operates there. The administrator must explicitly select the supported data residency location.
How Forge Storage Migration Works
Forge data residency is integrated with Atlassian's data residency infrastructure.
The process is initiated by the organization administrator rather than by an individual Forge application developer.
A simplified workflow looks like this:
Atlassian Organization Admin
|
v
Select Target Data Region
|
v
Schedule Data Migration
|
v
Atlassian Migrates Jira Data
|
v
Forge Hosted Storage Migrates
|
v
Migration Completes
|
v
Forge Application Resumes
The migration includes the hosted storage associated with the Atlassian product.
This reduces the need for developers to maintain separate migration infrastructure for KVS, Custom Entity Store, Forge SQL, and Object Store.
However, applications should be designed to tolerate temporary unavailability during the migration.
What happens to Forge applications during migration?
During a data residency migration, Forge suspends application execution for the affected installation.
This affects:
- Forge function invocations.
- Product event triggers.
- Application UI extensions.
- Access to application functionality.
Product events are queued and replayed after the migration completes.
This distinction is important. The Jira product and its users may experience a migration window, so developers should not promise that every Forge app feature remains available throughout the operation.
The application should instead recover correctly when execution resumes.
Supported Forge Data Residency Locations
Atlassian supports multiple locations for Forge-hosted storage.
Location | Region |
|---|
Australia | Asia Pacific (Sydney) |
Canada | Canada (Central) |
EU | Europe (Frankfurt and Dublin) |
Germany | Europe (Frankfurt) |
India | Asia Pacific (Mumbai) |
Japan | Asia Pacific (Tokyo) |
Singapore | Asia Pacific (Singapore) |
South Korea | Asia Pacific (Seoul) |
Switzerland | Europe (Zurich) |
United Kingdom | Europe (London) |
USA | US East (North Virginia) and US West (Oregon) |
The Global location is also available. In this configuration, Atlassian determines where in-scope data is hosted and may move it between supported realms as needed.
The exact location options depend on the Atlassian product and the organization's eligibility.
Step 1: Identify Which Storage Your Forge Application Uses
Before planning a migration, identify where your application stores customer information.
Consider a Jira application that maintains project configuration and issue-processing information.
It might use the following storage design:
Application data | Storage option |
|---|
User preferences | Key-Value Store |
Project configuration | Custom Entity Store |
Structured business records | Forge SQL |
Large application files | Forge Object Store |
External integration data | External database |
The first four options use Forge-hosted persistent storage and participate in supported Forge data residency migration.
External databases require separate consideration.
If your application stores customer information in an external database, moving Jira and Forge-hosted storage does not automatically move that external data.
You must manage its regional location separately.
Step 2: Use Forge-Hosted Storage for Persistent Application Data
Whenever possible, use the appropriate Forge storage capability for persistent application information.
For example, the Key-Value Store can hold application configuration.
import { kvs } from "@forge/kvs";
export async function saveProjectConfiguration(
projectKey,
configuration
) {
if (!projectKey || !configuration) {
throw new Error("Invalid project configuration");
}
await kvs.set(
`project:${projectKey}`,
configuration
);
}
export async function getProjectConfiguration(
projectKey
) {
return await kvs.get(`project:${projectKey}`);
}
This example stores and retrieves project configuration using Forge-hosted storage.
The benefit is that the application does not need to manage its own database replication or regional migration process for these records.
For structured data with relationships and query requirements, Forge SQL or Custom Entity Store may be more appropriate.
Choose the storage capability based on the application's access patterns rather than using KVS for every type of information.
Step 3: Prepare the Application for Temporary Unavailability
Although Atlassian manages the storage migration, developers must make sure the application can recover when its functions become available again.
For example, consider an application that receives Jira issue events and updates an internal project counter.
During migration, those events may be queued and replayed afterward.
If the application assumes that every event is delivered only once, replayed events could create duplicate updates.
A better approach is to make event processing idempotent.
An idempotent operation produces the same final result even when the same event is processed more than once.
A simplified implementation might look like this:
import { kvs } from "@forge/kvs";
export async function processIssueEvent(event) {
const eventId = event.eventId;
if (!eventId) {
throw new Error("Event ID is required");
}
const processedKey = `processed:${eventId}`;
const existing = await kvs.get(processedKey);
if (existing) {
return {
status: "already-processed"
};
}
// Perform the required business operation here.
await updateProjectMetrics(event);
await kvs.set(processedKey, {
processedAt: new Date().toISOString()
});
return {
status: "processed"
};
}
async function updateProjectMetrics(event) {
// Application-specific processing logic.
}
This example illustrates the idempotency pattern, not an atomic exactly-once transaction.
In production, checking an event key and then updating a separate record must be designed carefully. Concurrent deliveries can still create race conditions.
Use a storage operation with appropriate uniqueness or transactional guarantees, where available, to make duplicate protection reliable.
Also, verify that the event identifier is stable and unique for the event type being processed.
Step 4: Review External Storage and Forge Remote Integrations
Not every Forge application uses only Atlassian-hosted storage.
Some applications connect to external services using Forge Remote.
For example, an application might store customer-specific reports in an external PostgreSQL database hosted in AWS.
Moving Jira data to another region does not automatically migrate that external database.
Forge supports remote data residency through region-specific baseUrl configurations and the realm migration mechanism.
Developers using Forge Remote must implement the required migration support.
This may involve:
- Preparing the destination region.
- Moving external application data.
- Updating regional endpoint configuration.
- Validating data consistency.
- Handling migration lifecycle events.
- Declaring the expected migration duration.
Unlike standard Forge-hosted storage, remote storage migration requires application-specific implementation.
Step 5: Handle Forge Remote Migration Events
Forge provides a migration module for applications that need to manage their own remote data migration.
A simplified manifest configuration looks like this:
modules:
migration:
- key: remote-data-migration
endpoint: remote-api
operations:
- migrate
The exact manifest configuration must follow the current Forge Remote migration module schema and match the endpoint configuration of the application.
The migration endpoint is responsible for coordinating the application-specific data movement.
A remote migration implementation should be designed to:
- Identify the source and destination regions.
- Export the required application data.
- Transfer the data securely.
- Validate the destination records.
- Confirm that the destination service is ready.
- Complete the migration lifecycle successfully.
Atlassian evaluates migration eligibility when scheduling the operation.
Applications with remote migration requirements must also account for the documented migration window and downtime considerations.
For Forge-hosted storage, these custom remote migration hooks are not required.
Understanding Product Events During Migration
One of the most important considerations is how the application handles events that arrive during a migration.
Suppose a Jira project receives 500 issue updates while its Forge application is suspended.
Developers should not assume that all 500 events will be processed immediately.
The platform queues eligible product events and replays them after the migration.
This can temporarily increase the amount of work the application needs to process.
For example, an application that normally handles five events per second may receive a larger backlog when execution resumes.
To manage this situation:
- Keep event handlers efficient.
- Make processing idempotent.
- Avoid unnecessary external API requests.
- Use asynchronous processing for expensive operations.
- Monitor invocation failures and retry behavior.
- Ensure that the application can recover from temporary dependency failures.
Do not use a migration window as an opportunity to assume that event ordering or exactly-once processing is guaranteed.
Your event-handling logic should tolerate retries and repeated delivery.
Monitoring Regional Migration
Forge provides audit logs in the Developer Console to help developers monitor data residency-related activity.
These records can contain information about:
- Migration scheduled.
- Migration started.
- Migration completed.
- Migration failed.
- Current data location.
- Target data location.
For example, an audit event might identify a migration from Global to India for a particular Forge app installation.
These records are useful when investigating whether an application has completed its regional migration.
You should also monitor normal application health after the migration.
Useful indicators include:
Metric or signal | What to investigate |
|---|
Function invocation failures | Whether application execution has resumed |
Product event backlog | Whether queued events are being processed |
Storage operation errors | Whether storage access is working correctly |
External API failures | Whether regional endpoints are reachable |
Processing latency | Whether the application is recovering normally |
Duplicate processing | Whether idempotency controls are working |
For applications with external services, monitor both Forge and the external infrastructure.
Common Mistakes During Forge Storage Migration
Assuming developers must manually copy Forge-hosted storage
Standard Forge-hosted storage migration is managed by Atlassian.
Creating a separate export and import process for KVS or Forge SQL is generally unnecessary for a normal data residency move.
Assuming Jira and Forge apps remain fully available
Forge app functions and UI extensions can be unavailable during the migration.
Design the application to recover after the migration rather than promising uninterrupted execution.
Ignoring queued events
Events may be replayed after migration.
Applications that are not idempotent can produce duplicate business operations.
Forgetting external databases
External storage is not automatically covered by Forge-hosted storage migration.
Its regional movement requires a separate plan.
Treating region pinning as complete compliance
Data residency is only one part of a broader compliance strategy.
Review logs, external integrations, backups, encryption, and other data-processing activities separately.
Best Practices for Production Forge Applications
- Prefer Forge-hosted persistent storage when it satisfies application requirements.
- Document every external service that stores customer information.
- Implement idempotent product event handlers.
- Avoid storing persistent information in temporary execution memory.
- Test application recovery after simulated periods of unavailability.
- Monitor migration audit events through the Developer Console.
- Design asynchronous processing to handle backlogs.
- Keep external services region-aware when using Forge Remote.
- Validate destination data before completing a remote migration.
- Review data residency requirements with organization administrators before deployment.
- Avoid hardcoding a single geographic endpoint when region-specific endpoints are required.
- Maintain an operational recovery plan for failed migrations and external dependency outages.
Advantages and Disadvantages of Forge-Managed Data Residency
Advantages
- Atlassian manages regional migration for supported hosted storage.
- Developers do not need to maintain custom database replication for Forge-hosted data.
- Supports multiple geographic data residency locations.
- Aligns Forge-hosted application data with the host Jira or Confluence location.
- Reduces operational work for applications using native Forge storage.
- Provides migration audit information for monitoring.
Disadvantages
- Application execution can be temporarily unavailable during migration.
- Developers have limited control over the underlying storage migration process.
- External databases require separate migration planning.
- Remote applications need additional migration support.
- Product event backlogs can affect processing after migration.
- Data residency does not automatically cover every external service or processing activity.
Summary
Moving Atlassian Forge application storage between regions is primarily managed through Atlassian's data residency infrastructure when applications use persistent Forge-hosted storage.
When an organization administrator moves Jira or Confluence data to a supported region, eligible Forge application data moves with it. Developers do not need to implement a separate database export and import process for standard hosted storage.
However, the application must be prepared for temporary unavailability. Forge functions and UI extensions may be suspended, while eligible product events are queued and replayed after migration.
The situation is different for Forge Remote applications that maintain external databases. Those applications need region-aware endpoints and application-specific migration support.
The most reliable approach is to use Forge-hosted storage where practical, implement idempotent event processing, monitor migration audit records, and manage external data locations separately.
This architecture allows organizations to meet data residency requirements while minimizing custom migration work and reducing the risk of data inconsistencies.
Join the conversation! Your thoughts help the community grow.