Last updated Feb 21, 2024

Limitations and differences

There are currently some incompatibilities and differences when registering your existing Connect app on Forge.

If you're blocked by one of these limitations, make sure you watch the related Jira issue (press W on your keyboard). Along with keeping you up to date, this also helps us prioritize the most needed features.

Incompatibilities

At present, you shouldn't attempt to register your app on Forge if your app uses these Connect features:

Differences

When adopting Forge for your Connect app, there are some differences and caveats to what a developer may be used to:

  1. The first update to Forge will require Admin approval (major update)

  2. Non-admin-approved updates will roll out quickly, without callbacks

  3. License must stay consistent

  4. Updates to Forge will show as a 'new installation' in audit log

  5. Modules will not migrate from Connect to Forge types

  6. App keys need to be manually handled across dev/stage/prod

1. The first update to Forge will require Admin approval (major update)

Currently even without changing anything else, publishing your existing app as a Forge app will trigger a major update for Admins. If you prefer to minimize the number of major version app updates for your customers, we recommend bundling up an app update with the introduction of your first Forge module.

Once your app is registered with Forge, the enabled and disabled Connect lifecycle events will no longer be sent.

See Versioning in Connect Vs Forge for more detail on how versioning is different.

2. Updates that do not require admin approval (automatic updates) will roll out quickly, without callbacks

For a Forge app using Connect modules, updates that do not require admin approval - automatic updates (micro updates for Connect, minor updates for Forge) will roll out at the same speed as Forge updates (within minutes).

Once your app is registered with Forge, the installed Connect lifecycle event will no longer be sent during automatic updates.

See Versioning in Connect Vs Forge for more detail on how versioning is different.

Watch this Jira issue for updates.

3. License must stay consistent

When registering your existing Connect-only app on Forge, the licensing must stay consistent.

A paid connect app (enableLicensing: true in the descriptor) must be replaced by a paid Forge app (app.licensing.enabled: true), and an unpaid Connect app by an unpaid Forge app.

The licensing status of the app can't be changed until all installations have migrated to Forge. There are currently no plans to address this, as it only affects apps that are in the process of updating to a Forge version.

4. Updates to Forge will show as a 'new installation' in audit log

An update that moves from Connect-only to adopting Forge shows as a new installation in the UPM audit log. There are currently no plans to address this.

Screenshot of audit log, showing a log message of a new app installed, when an app updates to the Forge version

5. Modules will not migrate from Connect to Forge types

There is no support for migrating saved modules from their Connect types to their Forge equivalents. For example, if a Connect-based Confluence macro is removed and a Forge-based macro added, all existing instances of the macro saved in pages will stop working.

Watch this Jira issue for updates on our plans to address this issue for macros.

6. App keys need to be manually handled across dev/stage/prod

app.connect.key can and should be set differently in different environments, but the field in the manifest is not environment-specific. This means app.connect.key needs to be changed to the appropriate key before running forge deploy to different environments.

See Developing with Connect and Forge for more information on how to best handle app keys.

Next steps

Now that you're aware of the differences, you're ready to start adopting Forge in your Connect app.

Rate this page: