Private Connect → Forge migration checklist

Atlassian says Connect end of support begins on 31 January 2027. That does not mean every private app stops working on that date. It means support narrows, compatibility can deteriorate and teams maintaining private Connect apps must plan their own transition. Read Atlassian's private-app guidance.

1. Discover and classify the apps

Start at the Atlassian Connected apps administration interface. Atlassian is displaying warnings for private Connect applications, including apps with no declared Forge migration intent. Your inventory should identify every app's maintainer, target products, users, business owner and critical workflows. The descriptor alone is not a complete inventory.

• Confirm whether each app is private/custom or a Marketplace product maintained by a vendor.
• List Connect descriptor module types and instances, associated REST endpoints, webhooks and scheduled jobs.
• Determine whether the original maintainer and source code are still available.
• Record any external database, secrets manager, queue, support integration or billing dependency.
• Identify a business owner who can validate the current behavior before it changes.

Source: Atlassian — what administrators see.

2. Preserve installation identity

For Forge apps that adopt an existing Connect identity, do not discard the original Connect app key just because its modules are gone. Atlassian's official adoption-status tool checks the manifest and calls out missing identity linkage. It is free, and should be part of your own release pipeline.

npx @atlassian/connect-to-forge@latest adoption-status --strict

Use this command inside the authorized development environment containing the app's manifest.yml. It reports whether Connect modules/scopes remain and can fail CI when important adoption checks fail. It does not migrate application logic, stored data, webhooks or permissions for you.

• Review original app key and current Forge manifest key relationship before any upgrade.
• Identify what is already native Forge and what is still running as a Connect module or backend.
• Run the official status check with the exact manifest and preserve results as release evidence.
• Check version, install and update behavior on a non-production cloud tenant.

Source: Atlassian — Checking Forge adoption status.

3. Protect custom fields, content and historical data

Some small apps keep all of their business logic in a simple issue panel. Others own custom field types, Confluence macro parameters, entity properties, or externally persisted configuration. The second category is a different migration project, even if its manifest looks short.

• Capture each custom field's original key, value type, usage in JQL/workflow rules and historical values.
• For Jira Connect jiraIssueFields, study Atlassian's documented replacement in Forge jira:customField using the same key and migratedFromConnect: true before deployment.
• For Confluence custom content or macros, inspect whether the original content type and parameter schema require compatibility transformations.
• List stored entity properties, external database records, tenant IDs and lifecycle events; document who owns their backup and restore.
• Record whether a business workflow depends on a precise identifier or query syntax that may change.

Sources: Jira issue field migration, Confluence custom content migration.

4. Review permissions and backend boundaries

Connect JWT authentication, user impersonation and app-level scopes do not automatically carry over as equivalent Forge permissions. Assess least privilege per API call and UI surface, including data access where site admins or end users lack rights.

• List legacy Connect scopes and map each operation to required Forge scopes and execution identities.
• Test unauthorized and cross-tenant access, not only happy-path operations in an admin account.
• Check whether a backend moves fully to Forge functions, must use Forge Remote, or remains deliberately external.
• Verify any OAuth consent/version changes and customer administrative approvals.
• Check install/uninstall lifecycle assumptions: Atlassian changed Connect uninstalled hook behavior during Forge-only upgrades in 2026.

5. Stage, test and cut over safely

Staged release acceptance should focus on the business workflow users rely on, rather than merely passing a build. Running the official migration-status tool and rendering a page is not enough.

• Use a permitted cloud development or staging site and keep the existing production app untouched until approval.
• Record feature-parity tests for key modules, custom fields, webhooks, permission-denied states, failure retries and configuration.
• Compare before-and-after sample data with customer-approved redacted fixtures and explicit acceptance thresholds.
• Document rollback feasibility and its limits; irreversible data-shape changes require a separately approved path.
• Validate Forge platform usage budgets and any potential overage obligations before enabling billed capabilities.
• Secure a written production go/no-go decision from the authorized customer owner.

6. Decide whether to migrate, replace or retire

If the original developer is gone, source code is inaccessible, or a custom workflow has only a handful of users, a like-for-like port may not be the best investment. A valid assessment should offer three explicit outcomes: a bounded Forge implementation, a supported alternative that replaces the feature, or a supervised retirement with a documented data export plan.

• Identify the real owner and business value of each remaining custom function.
• Estimate complexity based on modules, stored data, deployment boundary and tenant-specific workflows.
• Compare migration effort with buying a currently supported application or removing the function safely.
• Reject any fixed-price promise that silently includes extensive customer field migrations or production cutover.

Official primary references

1. Connect End of Support and private/custom apps — scope, date and administrator guidance
2. Adoption status CLI — manifest checks, strict CI mode and Connect identity preservation
3. Jira issue fields — preserving keys and data during field migration
4. Confluence custom content — backwards-compatibility behavior
5. Atlassian migration changelog — track current behavior changes

This page is an independent, non-legal engineering checklist updated in October 2026. Atlassian may revise its migration guidance. No specific app is certified or declared ready to migrate based on these steps alone.