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 at the top of the Knock dashboard to quickly create a new branch. By default, you'll be on the main 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 at the top 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 at the top 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.

You can also pass in the optional --branch flag to specify the branch you want to work with.

If you need to overwrite existing content in Knock (for example, when local changes should replace what is currently stored), you can add the --force flag to the push command.

When main moves ahead while you're working on a branch, you can rebase the branch to bring in the latest changes from main while preserving your branch's commits. Rebase updates your branch in place. It does not promote your branch's changes to main — use merge for that.

Rebasing always syncs a branch onto main in the development environment. You cannot rebase onto staging, production, or another branch.

In the dashboard

When your branch is behind main, Knock shows a banner on the Commits page indicating how many commits behind you are. You can rebase from there, from the branch selector, or when resolving a merge conflict.

In the CLI

See the CLI reference for flags and error handling.

During a rebase, Knock compares each resource on main with the same resource on your branch and applies automatic resolution:

Situation	What happens
You have unmerged commits for a resource on the branch	Your branch version is preserved
You have not changed a resource on the branch	The branch receives the latest committed version from main
A resource exists on main but not on the branch	The resource is copied into the branch

Knock does not perform a Git-style three-way merge or per-field conflict resolution during rebase. For resources you have changed on the branch, your branch's version wins automatically.

Rebasing also resets the conflict-detection baseline for your branch. If the branch and main both changed the same resource and Knock previously flagged a merge conflict, rebasing can clear that conflict by absorbing the changes from main that your branch had not modified.

Rebase may be blocked when you have unpublished changes on shared resources where main has moved ahead since your branch last synced. In that case, commit or discard the blocking drafts before rebasing. Knock returns an error listing the affected resources.

Rebase is not blocked by:

• Unpublished changes on resources you have already committed to on the branch
• Unpublished changes on resources that exist only on your branch
• Unpublished changes on shared resources where main has not changed

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, delete, rebase, and merge 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, delete, and rebase 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.
• Rebase is only available in the development environment and always targets main.
• Rebase uses automatic branch-wins resolution. Knock does not provide per-field merge or conflict resolution during rebase.
• Rebase may be blocked when you have unpublished changes on shared resources where main has moved ahead. Commit or discard those drafts before rebasing.
• If you have merge conflicts on a resource that is part of a branch, you can rebase the branch to absorb non-conflicting changes from main, or resolve the conflicts outside of the dashboard via the CLI in order to continue.
• 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.