Branches & Merging
Branches are used to develop and test new versions of your Business Logic and API. You can Merge Branches for seamless development workflows.
A Branch is a copy of a workspace's business logic (APIs, Functions, Addons, and Tasks). They are most useful for testing and developing new versions of your app without affecting your customers' primary experience.
You can create new Branches and select which Branch to make a copy of, choose which Branch to make edits to, and select which Branch you want to be live for your API.
Branches can also merge from a source Branch to a destination Branch to make managing development, test, and live environments as seamless as ever.
Branches tutorial before merge capabilities were introduced.
Your initial Branch will be considered v1 of your business logic. Below your workspace name, you will be able to identify which Branch you are currently editing.
Automatically, you will start on v1.
Select the Branch identifier located underneath the workspace name.
This will allow you to see and change which Branch you are currently editing and which is live for your users, and allow you to add a new Branch.
When you select Add new Branch you will be able to choose a source Branch to make a copy from, the name of your new Branch, and a description.
Adding a new Branch makes a copy of the source Branch at that given time. So for example, if you create v2 from source Branch v1, you will have all the same business logic (APIs, Functions, Addons, and Tasks).
The Branch you are currently editing will be identified underneath the workspace name on the left menu column. To change this, click on the Branch name to open up the menu of the different Branches in your workspace.
Select a Branch you wish to edit or set live and you will have the option to do so.
Edit or Set Live a Branch.
When a Branch is set live, it is the Branch or version of your API endpoints and business logic that will be live for your users.
If you wish to call an API endpoint from a Branch that is not live, you can do so by adding the branch name after the canonical, for example:
If the live branch is:
You can access a different branch by adding :branch name after the canonical:
You can also use a Set Http Header function, to set the X-Branch header followed by the Branch name. For example:
Setting this on an API endpoint would force that endpoint to call the v2 Branch version of the endpoint.
While making changes in your workspace, you can differentiate if your Branch is live or not with the color of the Branch name in the left menu column.
When the Branch name is blue, the Branch is live:
v1 is Live.
If the Branch is yellow, it is not live:
v2 is not live
When editing a Branch that is not live, the Swagger documentation and API Endpoint URL buttons will provide the version of that Branch and not the live Branch.
To get the URL of the live Branch either remove the :branch name after the canonical or go to the live Branch.
Merging Branches allows for seamless development management of different environments. It allows you to update a destination Branch with changes and updates created from a source Branch. Merging will include changes to published objects such as APIs, Functions, Addons, and Tasks, and newly created ones.
For example, your live Branch is v1. You are editing v2, which has some new API endpoints for a new feature you are rolling out. During the development phase of v2, you had to modify an API endpoint in v1. When you're ready to merge v2 into v1, Xano will add the new API endpoints from v2 and maintain the update to the API endpoint on the destination v1 Branch.
To merge Branches open the Branches menu by selecting the Branch name under the Workspace name in the left-hand navigation bar.
Open the Branches menu.
Next, select Merge Branches.
Select Merge Branches.
After selecting Merge Branches, Xano will ask you to select the source Branch.
The Source Branch is the Branch containing the updates and modifications that you want to merge into the Destination Branch.
Choose the Source Branch - the Branch with new changes or updates.
Next, select the Destination Branch to merge the changes from the Source Branch. You can also choose if you would like the destination branch to be backed up prior to the merge.
The Destination Branch is the Branch where the updates will be merged into.
Select the Destination branch, and if you want the destination branch backed up before the merge
Then, Xano will display a confirmation page with all the Workspace objects receiving updates or new items.
If there is a change you do not want to include in the merge, select the settings icon next to the Workspace object and deselect the change to remove it from the merge.
Edit what's included in the merge.
Deselect specific changes to remove from the merge.
Once satisfied with all the updates included in the merge select publish to merge the Branches.
Select Publish to merge the Branches.
If after you have merged branches, you would like to restore from a backed up branch, click on the branches option, and check the "Include Backups" checkbox. This will show you all available backups, which you can then click and edit or set live just like any other branches. Setting live the backed up branch will allow you to quickly roll back to before the merge was made.
Use the Include Backups option to show backups made during branch merge.