# Migrate from Connect to Forge

Move your existing Jira or Confluence integration to the new Atlassian Forge app — no reconfiguration and no data loss.

Atlassian is retiring its older **Connect** app framework in favor of **Forge**. If you set up your Jira or Confluence integration before Forge was available, this guide walks you through moving to the Forge app.

The migration is designed to be seamless:

- **No reconfiguration.** Your projects, department mappings, sync settings, and knowledge indexes carry over automatically.
- **No data loss.** Existing tickets, comments, and indexed pages are preserved.
- **Minimal downtime.** Sync continues right after the Forge app is installed.

> **Note:** **Are you affected?** Only integrations set up on the older Connect framework
> need to migrate. Open **Settings → Integrations → Jira**. The **Jira app**
> card's **Method** row shows which app you use: **Forge**, **Connect
> (legacy)**, or **Forge + Connect (migrating)**. If it shows **Connect
> (legacy)**, or the Confluence card offers **Install New App**, you're still on
> Connect and this guide is for you. If you set up recently, you may already be
> on Forge, and no action is needed.

## Before you start

- **Risotto admin** access to your organization's dashboard.
- An **Atlassian organization admin** available to approve the app installation. See [Make someone an organization admin](https://support.atlassian.com/user-management/docs/give-users-admin-permissions/#Improved-user-management-experience).
- Your Atlassian **site URL** (e.g. `yourcompany.atlassian.net`).
- About 10–15 minutes. Metadata reloads in the background afterward.

## Migrate your integration

### Jira

1. **Open the Jira integration**

   In your Risotto dashboard, go to **Settings → Integrations** and click the **Jira** card. The **Jira app** card shows a green **Connected** status. Its **Method** row shows **Connect (legacy)**, its **Site** row shows your Atlassian site, and its **Installed** row shows a date.

2. **Start the migration**

   Click **Migrate to Forge** in the **Method** row. You can also click the **Connected** dropdown on the Jira card and choose **Migrate to Forge…**.

   A dialog opens with your existing Jira site already filled in. Confirm the site URL and click **Get install link**.

3. **Install the Forge app**

   Click **Open install page** to open Atlassian in a new tab. The Atlassian page for the **risotto-jira** app lists the permissions it requires:

   - View Jira issue data
   - Create and manage issues
   - View user profiles
   - Manage Jira global settings
   - Read Email Address
   - View workflows
   - Access and interact from outside of Atlassian

   Click **Get app**, choose the Jira site to install it on, and click **Install** to add the Risotto Forge app to your site.

4. **Confirm**

   Return to the Risotto dialog. The installation is detected automatically — the dialog changes to **Jira Forge App Installed** with a green checkmark and the message "Your Jira integration is ready to use." Click **Done**.

   > **Tip:** Project metadata reloads in the background. You can safely close the
   > dialog and keep working.

### Confluence

1. **Open the Confluence integration**

   In your Risotto dashboard, go to **Settings → Integrations** and click the **Confluence** card. The **Page updates** card shows a green **Connected** status.

2. **Install the Forge app**

   Click the **Connected** dropdown on the Confluence card and choose **Install New App…**. Then click **Open install page** to open Atlassian in a new tab. The Atlassian page for the **risotto-confluence** app lists the permissions it requires:

   - Read Confluence detailed content
   - Read Confluence content summary
   - Write Confluence content
   - Access and interact from outside of Atlassian
   - Share data with 1 domain outside of Atlassian

   Click **Get app**, choose the Confluence site to install it on, and click **Install**.

3. **Confirm**

   Return to the Risotto dialog and click **Continue**. The **Page updates** card on the Confluence page shows a green **Connected** status, with a link to the knowledge indexing settings that control which Confluence spaces and pages are indexed. Installing the Forge app on the same Atlassian site automatically links it to your existing Confluence connection, so your indexes keep working.

   The migration does not change how Risotto reads your pages. Each Confluence index reads page content with the **API token** and **Email address** saved on the index, not through the Atlassian app. The app only tells Risotto when a page changes, so that the index updates in real time. If you remove the Connect app before the Forge app is installed, real-time updates stop until you install it. **Reindex** still works. See [Confluence](https://www.tryrisotto.com/docs/integrations/knowledge/confluence).

   > **Tip:** If you've already migrated Jira on the same Atlassian site, Confluence
   > links to that connection automatically.

> **Note:** **Multiple workspaces on one Atlassian site?** If your company connects more
> than one Risotto workspace to the same Atlassian site, migrate from **one
> workspace only** — the others are linked to the same installation
> automatically and don't need to migrate. If you're not sure whether this
> applies to you, [contact support](mailto:support@tryrisotto.com) before
> migrating.

## Verify the migration

Before removing the old app, confirm the Forge integration is healthy:

1. The integration card shows **Connected**. On the Jira card, the **Method** row shows **Forge + Connect (migrating)** while both apps are installed, and **Forge** after you remove the Connect app.
2. **Jira** — create or update a test issue in a synced project and confirm the change appears in Risotto (and vice versa).
3. **Confluence** — edit an indexed page and confirm the update is reflected in search after a few minutes.

> **Done:** Once a test ticket or page update syncs both ways, your migration is complete.

## Remove the old Connect app

After you've verified the Forge integration is connected and syncing, remove the old app so both aren't installed indefinitely.

1. **Uninstall in Atlassian**

   In your Atlassian admin console, uninstall the **previous Risotto app** (the Connect app installed before this migration).

2. **Confirm sync continues**

   Back in Risotto, confirm the integration still shows **Connected** and that a test ticket or page update still syncs.

> **Warning:** Only remove the old app **after** you've verified the Forge integration is
> working (see [Verify the migration](#verify-the-migration)). Risotto detects
> your active Forge installation and preserves your projects, mappings, and
> credentials when the old app is removed — but verifying first avoids any gap
> in sync.

## Troubleshooting

### App installation fails

- Ensure you have **Organization admin** permissions in Atlassian.
- Check that the site URL is correct (e.g. `yourcompany.atlassian.net`).
- Confirm your Atlassian instance is a Cloud instance and reachable (not behind a restrictive firewall).

### Installation not detected

- Wait up to 60 seconds — detection happens automatically.
- If it still isn't detected, close the dialog and reopen **Settings → Integrations → Jira**; the installation may already have succeeded.
- Refresh the page and try again.

### Tickets or pages stopped syncing after migration

- Confirm the Forge app is installed and active in your Atlassian admin console.
- Check that the integration card shows **Connected**.
- Allow a few minutes for background metadata to finish reloading.
- If syncing doesn't resume, [contact support](mailto:support@tryrisotto.com).

### Forge migration verification failed: Missing projects

After the migration, Risotto compares the Jira projects the Forge app can see with the projects the legacy Connect app could see. If projects are missing, the **Jira app** card on **Settings > Integrations > Jira** shows **Forge migration verification failed** and lists the project keys after **Missing projects**.

A project is usually missing for one of these reasons:

- Someone deleted or archived the project in Jira after the Connect app last loaded your projects.
- The Forge app does not have the same access to the project as the Connect app had.

To run the check again:

1. Keep the Connect app installed.
2. If the Forge app cannot see a project that still exists, give the Forge app access to that project in Jira.
3. Go to **Settings > \<department> > Ticket Sync** and open the **Connected** menu on the **Jira Settings** row.
4. Click **Configure...**, then click the **Refresh Jira metadata** button (the refresh icon next to **Jira Site**).

Risotto removes a missing project from the check when the Connect app cannot see it either, for example because the project was deleted. For this, the Connect app must still be installed and connected. If Risotto cannot reach the Connect app, the check stays failed.

If the missing projects were deleted on purpose, you can also end the check. On the Jira card, open the **Connected** menu and click **Disconnect legacy Connect app...**. This clears a failed check. A passed check stays. If you uninstall the Connect app in your Atlassian admin console instead, the warning stays. In that case, [contact support](mailto:support@tryrisotto.com).

### I have multiple Risotto workspaces on one Atlassian site

- Migrate from a single workspace only; the others link to the same installation automatically.
- If a second workspace prompts you to migrate or reports an issue, [contact support](mailto:support@tryrisotto.com) rather than migrating it separately.

## Need help?

If migration verification fails or sync doesn't resume, contact support at <support@tryrisotto.com> with your Atlassian site URL and Risotto organization name.

Source: https://www.tryrisotto.com/docs/integrations/ticketing/migrate-connect-to-forge
