Connect-on-Forge app breaks after Jira site URL change due to missing installationId and host mapping

Forge
, , , ,
1

When the Jira site URL is changed (site rename / migration scenario), the app stops working in the Connect-on-Forge setup (because forge request are not authorized).

During the installation lifecycle:

  1. Atlassian raises the lifecycle event as installed

  2. Before our app’s installation logic executes, Atlassian’s internal logic:

    • Removes the installationId

    • Deletes the host entry from atlassian_host

    • Deletes the related record from atlassian_host_mapping

  3. After these deletions, our app’s AppInstalledEvent handler is triggered

At this point, both the installationId and host-mapping data are already missing, which causes our installation logic to fail.

Key Observation

  • Works as expected in pure Connect UI

  • Breaks in Connect-on-Forge (Forge Custom UI)

This makes it difficult to support instance URL changes during migration to Forge while keeping the Connect backend.

Impacte areas are:

  • Blocks safe migration from Connect UI to Forge Custom UI

  • Affects production customers during Jira site renames

  • No clear guidance on how to handle this scenario in Connect-on-Forge apps

Questions

  1. Is this behavior expected specifically for Connect-on-Forge apps?

  2. Is there a recommended way to handle Jira site URL changes when the backend is still Connect?

  3. Should apps rely on a different lifecycle event or identifier instead of installationId?

  4. Are there best practices or migration guidelines for this scenario?

3 Likes