Migrating app versions between environments

Generate a credential in the target environment

Migration requires an API credential issued from the target environment. This token must belong to an account with admin permissions; tokens for non-admin accounts fail target validation.

1. Sign in to the target environment as an organization admin.

2. On the target environment, create an API credential to use during migration.

   • AI Hub token — In the target environment, open Settings > APIs, then create a token for an admin account. Copy the token value before you close the dialog.

   • OAuth provider token — If your organization uses an external OAuth provider for API access, request an access token from that provider for an admin-mapped account on the target environment. Paste the access token, not the OAuth client secret.

Migrate an app version from the source environment

1. In the source environment, open the Hub, then the app to migrate.

2. Select the Versions tab.

3. For the app version to migrate, click the overflow icon (More actions), then select Migrate to another environment.

4. In the Migrate app dialog, complete information about the target environment.

   1. In Target environment URL, enter the full target AI Hub URL. For example, https://target-environment.instabase.com.

   2. In Token type, select AI Hub token or OAuth provider token.

   3. Enter the Token value (for an AI Hub token) or Access token (for an OAuth provider token).

   4. Click Fetch organization. Verify the target organization details.

   5. Click Next.

5. On the App info tab, select an App migration type.

   • Migrate as a new app — Creates a new app in the target environment. Enter the App name, App description, and App icon. Migrating as a new app doesn’t create a linked project on the target.

   • Migrate to an existing app — Adds a new version to an existing app in the target environment. Enter the App ID in target environment, then click Fetch data. Confirm the resolved Target app name.

     You can find an app ID in the app URL, such as https://aihub.instabase.com/hub/apps/528c36e8-ac5b-490d-a41b-7eec9c404b87.

   • Migrate to an existing project — Enter the Project ID in target environment, then click Fetch data. Confirm the resolved Target app name. Use this option when you want the migrated version linked to that project on the target.

     You can find a project ID in the project URL, such as https://aihub.instabase.com/build/528c36e8-ac5b-490d-a41b-7eec9c404b87.
   Advanced apps have additional restrictions: you can’t migrate an advanced app onto a standard (non-advanced) app, and Migrate to an existing project isn’t available. In that case, migrate as a new app or onto an existing advanced app.

6. Click Next.

7. Complete Version info:

   • Version — If you’re updating an existing target app, select Major, Minor, or Patch. If you’re creating a new app on the target, enter a semantic version such as 0.0.1.

   • AI runtime updates — Select whether the app adopts the latest AI runtime version automatically as soon as it’s released, or when the current version expires, which allows time for testing and manual deployment.

   • Release notes — Describe what changed in this app version.

   Migrated apps use private visibility. Manage access through the app’s sharing settings after migration. For more details, see Sharing apps.

8. Click Migrate. Migration can take some time, a Migration complete alert indicates success.

   If migration fails, you see Migration failed. Click Try again to restart the process. A failed migration doesn’t leave orphaned files or a partial app on the target.