|
| 1 | +--- |
| 2 | +title: "Branches" |
| 3 | +description: "Learn how to use branches to isolate changes to your Knock resources." |
| 4 | +tags: ["version control", "branches", "environments", "commits"] |
| 5 | +section: Version control |
| 6 | +--- |
| 7 | + |
| 8 | +<Callout |
| 9 | + type="beta" |
| 10 | + text={ |
| 11 | + <> |
| 12 | + Branches are currently in beta. If you'd like early access, or this is |
| 13 | + blocking your adoption of Knock, please{" "} |
| 14 | + <a href="mailto:support@knock.app?subject=Branches">get in touch</a>. |
| 15 | + </> |
| 16 | + } |
| 17 | +/> |
| 18 | + |
| 19 | +## What are branches in Knock? |
| 20 | + |
| 21 | +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. |
| 22 | + |
| 23 | +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. |
| 24 | + |
| 25 | +Branches are a completely optional feature in Knock. If you don't use branches, you can still use Knock's [commit model](/version-control/commits) to version changes to your resources [in isolated environments](/version-control/environments). |
| 26 | + |
| 27 | +## Create a branch |
| 28 | + |
| 29 | +**In the dashboard** |
| 30 | + |
| 31 | +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. |
| 32 | + |
| 33 | +**In the CLI** |
| 34 | + |
| 35 | +```bash title="Creating a new branch in the CLI" |
| 36 | +knock branch create my-branch |
| 37 | +``` |
| 38 | + |
| 39 | +## Making changes on a branch |
| 40 | + |
| 41 | +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](/developer-tools/knock-cli) or [Management API](/developer-tools/management-api). |
| 42 | + |
| 43 | +**In the dashboard** |
| 44 | + |
| 45 | +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. |
| 46 | + |
| 47 | +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. |
| 48 | + |
| 49 | +**In the CLI** |
| 50 | + |
| 51 | +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. |
| 52 | + |
| 53 | +```bash title="Switching to a branch in the CLI" |
| 54 | +knock branch switch my-branch |
| 55 | +``` |
| 56 | + |
| 57 | +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. |
| 58 | + |
| 59 | +```bash title="Pushing and committing changes in the CLI for a branch" |
| 60 | +knock workflow push my-workflow --commit |
| 61 | +``` |
| 62 | + |
| 63 | +Optionally, you can also pass in the `--branch` flag to specify the branch you want to work with. |
| 64 | + |
| 65 | +```bash title="Pushing and committing changes in the CLI for a specific branch" |
| 66 | +knock workflow push my-workflow --branch my-branch --commit |
| 67 | +``` |
| 68 | + |
| 69 | +## Merging changes from a branch |
| 70 | + |
| 71 | +**In the dashboard** |
| 72 | + |
| 73 | +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. |
| 74 | + |
| 75 | +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. |
| 76 | + |
| 77 | +## Delete a branch |
| 78 | + |
| 79 | +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`. |
| 80 | + |
| 81 | +**In the dashboard** |
| 82 | + |
| 83 | +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. |
| 84 | + |
| 85 | +**In the CLI** |
| 86 | + |
| 87 | +```bash title="Deleting a branch in the CLI" |
| 88 | +knock branch delete my-branch |
| 89 | +``` |
| 90 | + |
| 91 | +## Working with branches in the API |
| 92 | + |
| 93 | +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. |
| 94 | + |
| 95 | +```bash title="Specifying a branch in the API" |
| 96 | +curl -X POST "https://api.knock.app/v1/workflows/my-workflow/trigger" \ |
| 97 | + -H "Authorization: Bearer $KNOCK_API_KEY" \ |
| 98 | + -H "X-Knock-Branch: my-branch" \ |
| 99 | + -d '{"recipient": "jhammond"}' |
| 100 | +``` |
| 101 | + |
| 102 | +Branches are fully supported in our server-side and client-side SDKs as well. |
| 103 | + |
| 104 | +```javascript title="Specifying a branch in the SDK" |
| 105 | +import Knock from "@knocklabs/node"; |
| 106 | + |
| 107 | +const knock = new Knock({ |
| 108 | + apiKey: process.env.KNOCK_API_KEY, |
| 109 | + branch: "my-branch", |
| 110 | +}); |
| 111 | + |
| 112 | +await knock.workflows.trigger("my-workflow", { |
| 113 | + recipient: "jhammond", |
| 114 | +}); |
| 115 | +``` |
| 116 | + |
| 117 | +## Working with branches in the CLI |
| 118 | + |
| 119 | +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. |
| 120 | + |
| 121 | +```bash title="Specifying a branch in the CLI" |
| 122 | +knock workflow list --branch my-branch |
| 123 | +``` |
| 124 | + |
| 125 | +It's also possible to use the CLI to programmatically create, update, and delete branches. |
| 126 | + |
| 127 | +## Working with branches via the Management API |
| 128 | + |
| 129 | +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. |
| 130 | + |
| 131 | +```bash title="Specifying a branch in the Management API" |
| 132 | +curl -X GET "https://control.knock.app/v1/workflows?branch=my-branch" \ |
| 133 | + -H "Authorization: Bearer $KNOCK_SERVICE_TOKEN" |
| 134 | +``` |
| 135 | + |
| 136 | +It's also possible to use the management API to programmatically create, update, and delete branches. |
| 137 | + |
| 138 | +## Limitations |
| 139 | + |
| 140 | +There are a few limitations to branches in Knock: |
| 141 | + |
| 142 | +- Branches are **only** available in the `development` environment. |
| 143 | +- 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. |
| 144 | +- 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. |
| 145 | +- There's currently no way to "rebase" a branch against `main` without using the CLI. |
| 146 | +- Branches are not supported for [broadcasts](/concepts/broadcasts). |
| 147 | +- Branches are not supported for [sources](/integrations/sources/overview). |
| 148 | +- Branches are not supported for [webhooks](/integrations/webhooks/overview). |
| 149 | + |
| 150 | +## Frequently asked questions |
| 151 | + |
| 152 | +<AccordionGroup> |
| 153 | + <Accordion title="What is the difference between a branch and an environment?"> |
| 154 | + A branch is a way to isolate changes to your Knock resources. It's like a |
| 155 | + sandbox for your changes. |
| 156 | + </Accordion> |
| 157 | + <Accordion title="What channel settings are used for a branch?"> |
| 158 | + Branches will always use the channel settings configured for the `development` environment (the `main` branch). |
| 159 | + </Accordion> |
| 160 | + <Accordion title="Can I block changes being made directly to my development environment?"> |
| 161 | + No, you cannot yet block changes being made directly to your development |
| 162 | + environment. However, we're considering this feature and would love to hear |
| 163 | + your use case if you'd like to see this feature. Please [get in |
| 164 | + touch](mailto:support@knock.app) and we can discuss your use case further. |
| 165 | + </Accordion> |
| 166 | + <Accordion title="Can I put an approval process in place before merging changes from a branch into the main branch?"> |
| 167 | + No, there's not currently a way to put a review process in place before |
| 168 | + merging changes from a branch into the main branch. |
| 169 | + </Accordion> |
| 170 | + <Accordion title="Is there a limit to the number of branches I can have in my account?"> |
| 171 | + No, there's no limit to the number of branches you can have in your account. |
| 172 | + </Accordion> |
| 173 | + |
| 174 | +</AccordionGroup> |
0 commit comments