A HubSpot Developers tutorial (hosted by Brooke) showing how to manually migrate a private app from platform 2025.1 to 2025.2. It walks through copying the project, disconnecting GitHub CI/CD, updating hsproject.json, adding/appending "-hsmeta" to source JSON filenames, adjusting JSON structure/field names (uid, type, data→config, title→name, module→entryPoint, objectName→objectType), renaming extensions→cards, and running "hs project upload" to create the new project. The video also notes that private apps keep the same access token after migration, and serverless functions must be moved to a third-party backend.
Questions this video answers
December 18, 2025.
2025.2.
private.
static.
context (read and write).
Chapters
Hey y', all, It's Brooke with HubSpot. Today I'm going to go over how you can manually migrate your private apps to the new project platform 2025.2. For public apps, you can actually use our automated migration command. And if you want to learn more about that, make sure to check out my video on the YouTube channel all about this. But in this video we're going to show you how you can manually move over a private app that is on 2025.1 to 2025.2. When you do this, you will be creating a new project inside of your account. So if you are using that private app access token anywhere, once you migrate your private app over, you won't need to update anywhere you have your old private access token. Additionally, if you're using serverless functions with your private app, you will need to migrate those over to a third party backend service. And we have a great blog post by senior developer advocate Hannah Seligson. So check out that it will be linked in the description below if you need to do that. All right, now let's look at our project inside of our account. So we're in our account and I'm going to go ahead and click on this HS Project 2025 one. This one is a very simple one. It only has a card and a webhook. So right now what you are seeing is the old UI for your project and if you click on Manage app, it will take you to the overview for this private app. Now let's go over to my IDE so I can show you how to manually migrate. So now we are in our IDE and the first thing I want you to do is I want you to copy your files. You don't want to lose anything, so make sure you go ahead and make a copy of this project so you won't lose anything. So let's go ahead and copy over this entire folder. We're going to just copy and then paste it right on in. Now we have a full copy of our folder that we're working with and if you are using a GitHub CICD pipeline with this, you will need to disconnect that from your project inside of your HubSpot account because because that will mess up when you're going through this. So just go ahead and do that before. Now the first thing you'll need to update is your hsproject JSON file inside of here. You'll need to update the name. So we'll just Change this from 20251 to 2025 2. And we'll also update the platform version and then we're going to go ahead and save that. Now we're going to go into our source folder and then we're going to open up our app JSON file. The first thing that we need to do is we need to go ahead and append hsmeta to this file name and then we can go ahead and add hsmeta. So this hsmeta is going to go on all of your JSON files inside of your source folder. So now what I like to do is I actually like to go ahead and look at an app hsmeta JSON file from a 20.25.2 project. This will go ahead and help me understand all of the things that are going to be updated about this file. So let's go into this test app here. That is a project 2025.2. I'm going to go into the source and then I'm going to open up the app HS meta JSON file here on the side. So now we can see all of the stuff that is different between these. So the first thing that we'll need to do is we will need to have our uid, which is here. And and because this is going to be a new one, we need to update the UID to be for the HS Project 2025 too. And then we also need to add in our type. So here our type is app. And then the last thing that we can do is let's just go ahead and delete out all of this other stuff because we don't need this information. So instead of having it set public false, we need to add in our config object and and then inside of our config object we can actually go ahead and take this config from here from our app hsmeta JSON file here and we can just go ahead and copy all of this over. And the only thing we'll need to do is make sure that we take out the name and the description here at the top, because the name and the description is now inside of our config. And so then we will make our description be an updated version of our HS Project 2025.1 app. And then our name will again be HS Project 2025.2. And now we should be good to go. We have the distribution set to private, so it will not need to use oauth. We'll have our authtype as static and our scopes were exactly the same from previous. We're just using context read and write. And then additionally we added in our information if we are going to use HS fetch and then information about the support information. So now we can go ahead and close out this app hsmeta JSON file and move on to inside of our other folders. So, so instead of the folder being named extensions, it now is named cards. So we're going to just rename this to cards and then we're going to go inside of here and we're going to go to our example card JSON file and we also need to rename this as well to have our dash HS meta at the end of it. So now what I'm going to do is I'm going to go ahead and open up the other HS meta JSON file that we have for our other card and we're going to just do the same thing that we did last time. We're going to compare them and add in the stuff that we need to. So the first thing that you'll notice is that the UID is at the top level. So in here it's inside of this data, but we need it to be at the top level. So I'm just going to go ahead and copy this right over and put it at the top and then I'll Change this to 2025 to and instead of the type being CRM card, now it's simply card. So we can remove CRM from that. And then the next thing we need to do is we need to change data to config because we don't have data in anymore as our object name is config. And then instead of title we do name and this is going to be our name of our card. Our location will stay the same. And then instead of having a module that tells you where the file is, we actually have entry point. So we're going to add in our entry point and then it will just tell us go inside of the app folder, inside of the cards folder and then call the correct one. So every time you add a new card to your project, you will need to set up a new HS meta file for that so that the project won't get them confused. And then the last thing is inside of this object types. Instead of having an object inside of here, all you need to do is just say what object type is going to be connected to. So in this case it's on the contact record page. So the final thing we're going to work on before we can upload this is our webhooks. So we're going to go into our webhooks folder and then we're going to rename our webhooks file and just again we are going to add the HSMIMA and now we're going to open it. And then I'm going to go into my other webhooks hsmeta and then go ahead and open that on the side. And so then we're going to see what is different between these two. So the first thing we notice is that we need the UID and the type. So let's go ahead and copy those into here. And then we're going to change this to be Webhooks HS Project 2025 2. So the next thing we see is that we need to wrap all of this information that's under Settings, subscriptions, legacy, CRM objects into a config property. So let's go ahead and create a new config property here and then we will go ahead and just add that to this whole thing. So then we're going to look through our different subscriptions and so instead of object name, we just need it to be object type. So I'm going to go ahead and change this to object type. And that's for the property change. One, the object creation, again, just the object type instead of object name. Now we're going to CD into our HS project folder and then we are going to go ahead and just run HS project upload. And so it will say it does not exist because we are creating a totally new project. So we're going to say, yes, we do want to do that. And then it will go ahead and build that out and if there's no issues, it will automatically deploy it. So now let's go into our HubSpot account. So now we're going to go to our development section and we're going to go to projects. And now we can see that we have HS projects 2025.1 and HS projects 2025 too. And both of these have the exact same cards and webhook subscriptions in them. But this one is now on platform version 2025.2, which means that we can now add the new features to this project. And if you no longer need your old project on an old platform version, you can go ahead and delete that out of your account. You can keep it there as well. It will live under this legacy app set section, but you won't be able to add any of the new features to it. Thank you so much for watching. If you have any questions, please make sure to drop them down below and I will be sure to answer them for you. But as always, make sure to like and subscribe to the HubSpot Developers YouTube channel. And I will see you all in another video. Bye, y'. All. Bye. Bye.
