Branches

Branches in Knock are a way to isolate changes to your Knock resources, like workflows, layouts, and guides. They're like sandboxes for your changes, allowing you to make changes to your versionable resources without affecting the main branch (your development environment), 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.

Branches share the same set of users, objects, and tenants as the main branch. In other words, if you add, remove, or update a user, object, or tenant on the main branch, the change will be reflected on all branches, and vice versa. This means you can instantly start testing the changes you make on a branch: as soon as you create a branch, you can send notifications to the same users, objects, and tenants as you would on the main branch.

Similarly, audience membership changes in the main branch are reflected in all branches: if a user is added to an audience on the main branch, they will be added to the same audience on all branches.

There are a few limitations to branches in Knock:

• Branches are only available in the development environment.
• 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.
• Audiences cannot be created or updated on a branch.
• Branches are not supported for broadcasts.
• Branches are not supported for sources.
• Branches are not supported for webhooks.