HubSpot Private App Projects Migration

Private app migration is not the same as public app migration. HubSpot's latest-platform migration documentation explicitly warns that migrating a legacy non-project-based private app to `2026.03` is not currently supported. That single sentence is enough to require cautious language in any checklist or client handoff.

Some private app modernization paths involve manually moving configuration, webhooks, UI extension code, app cards, backend logic, or token-handling assumptions. Treat the work as a technical discovery project before you describe a migration command.

If a private app includes serverless functions or backend behavior that is central to business logic, document the feature list before proposing a path. The correct output may be a manual plan, a net-new project-based app, or a deferred migration until official docs support the needed path.

Capture the app's current auth model, token storage, backend services, webhooks, UI extensions, serverless functions, CRM cards, and any scheduled jobs. A private app that only uses an access token has a different risk profile from a private app with custom UI and backend logic.

Record whether the existing app is legacy non-project-based or already project-based. Then compare that state to the current private app and latest-platform migration docs. If the source docs do not support automatic migration for the case, say that plainly.

For agency handoff, mark private app work as 'manual planning/review' unless a developer has rechecked the current official docs and documented a supported path.

Use: 'This private app needs source-checked migration planning before we choose a path.' Avoid: 'The CLI will migrate the private app.'

Use: 'The current official docs should be rechecked before any production upload or replacement.' Avoid: 'This checklist guarantees compatibility.'

Use: 'We can inventory configuration and identify a likely path to verify.' Avoid: 'This is an official HubSpot migration plan.'