Branches

Branches in Knock are a way to isolate changes to your Knock resources. They're like sandboxes for your changes, allowing you to make changes to your resources without affecting the main branch, or other branches in your account.

Knock branches are conceptually similar to Git branches, and are designed to be used in a similar way as part of your development workflow with Knock. You can create a branch, make changes to your resources, and merge those changes into the main branch when you're ready. Your Knock branches can mirror your Git branches, so that you can coordinate feature changes between your application and Knock.

Branches are a completely optional feature in Knock. If you don't use branches, you can still use Knock's commit model to version changes to your resources in isolated environments.

In the dashboard

You can create a new branch in the Knock dashboard by going to the Branches page in your account settings and clicking the "Create branch" button. Alternatively, you can type into the branch selector in the top left of the Knock dashboard to quickly create a new branch.

In the CLI

Once you create a branch, Knock will copy over all of the resources from the main branch into your new branch so they're available to be worked on. You can then select the branch you want to work on in the branch selector in the top left of the Knock dashboard, or alternatively you can work with your resources on the branch via the Knock CLI or Management API.

In the dashboard

You can select a branch via the branch selector in the top left of the Knock dashboard. Once you've selected a branch, making changes to your resources on that branch is the same as making changes to your resources on the main branch. You can edit workflows, layouts, audiences, and other resources just as you would on the main branch.

Any changes you've made to your resources will not be able to be called via the API until you commit those changes to the branch. You can commit changes under the "Commits" section of the dashboard, or under each resources "Changes" tab.

In the CLI

To work with your resources on a branch via the CLI, you can use the knock branch switch command to switch to the branch you want to work on.

Once you've switched to the branch you want to work on, you can make changes to your resources just as you would on the main branch. You can then push and commit those changes to the branch just as you would on the main branch.

Optionally, you can also pass in the --branch flag to specify the branch you want to work with.

In the dashboard

You can view the changes made to a branch in the Knock dashboard by going to the Commits page. From there you can navigate to the "Unmerged changes" tab to see all changes that have not been merged into the main branch.

When you're ready to merge the changes from a branch into the main branch, you can click the "Merge all changes" button to merge all commits from the branch into the main branch, or you can merge individual commits from the branch into the main branch.

Once a branch is merged into the main branch, you may wish to delete the branch from your account. Deleting a branch is a permanent operation and cannot be undone. Doing so will delete all of the resources in the branch, including all commits and changes made to your resources on the branch that have not been merged into main.

In the dashboard

You can delete a branch in the Knock dashboard by going to the Branches page in your account settings and clicking the "Delete branch" button next to the branch you want to delete.

In the CLI

Branches are fully supported in the Knock API so that you can execute workflows, create users, and manage preferences in a branch-specific environment. When making requests to the API for your branch, you must use the API key for your development environment, along with a special X-Knock-Branch header to specify the branch you want to work with.

Branches are fully supported in our server-side and client-side SDKs as well.

Branches are supported in the Knock CLI for all commands that interact with resources in your Knock account. You can always use the --branch flag to specify the branch you want to work with or set a .knockbranch file in your home directory to specify the branch you want to work with.

It's also possible to use the CLI to programmatically create, update, and delete branches.

When using the management API, you can specify the branch you want to work with by passing the branch query parameter to the API endpoint, similar to how you would specify the environment.

It's also possible to use the management API to programmatically create, update, and delete branches.

There are a few limitations to branches in Knock:

• Branches are only available in the development environment.
• Branches will not currently copy over any users, objects, or tenants from your development environment. In order to work with users, objects, or tenants on a branch, you'll need to create them manually in the branch.
• If you have merge conflicts on a resource that is part of a branch, you will need to resolve the conflicts outside of the dashboard via the CLI in order to continue.
• There's currently no way to "rebase" a branch against main without using the CLI.
• Branches are not supported for broadcasts.
• Branches are not supported for sources.
• Branches are not supported for webhooks.