Creating a Branch

First, navigate to Branching > Branches to view the list of existing branches. Click the Add button at the top right to create a new branch.

note

If you don't see this button, check that you have permission to create a branch.

Pick a unique name for your branch, and add a description if you like.

When a branch is first created, its status will show as "new," indicating that its corresponding PostgreSQL schema has not yet been provisioned in the database. A background job is queued automatically to perform this task, which may take anywhere from a few seconds to several minutes, depending on the size of your database.

tip

You can check on the status of the provisioning job under the Jobs tab of the branch view.

Once the branch's schema has been provisioned, the status will be updated to "ready," and the branch will become available to activate. You can activate a branch by selecting it from the dropdown menu at the top right.

When a branch is active, any changes you make in NetBox (aside from system resources such as users, permissions, etc.) will be reflected only within that branch. For example, if you create a new site while a branch is active and then switch back to main, the site will no longer appear. Switch back to the original branch, and the site will appear again.

Branch Details

Within the branch view, you'll notice several tabs. Each of these pertains to a different set of changes related to the branch.

• Diff — Provides a summary of all the objects that have been created, updated, or deleted within the branch.
• Changes Behind — Lists all changes that have been made in main since the branch was last synchronized. Synchronizing the branch will update it to include these changes.
• Changes Ahead — Lists all changes made within your branch. Merging the branch will replicate these changes into main.
• Changes Merged — Once a branch has been merged, this tab lists all changes that have been applied from the branch into main. (This tab appears only for merged branches.)
• Jobs — Lists the background jobs that have run against this branch, including provisioning, syncing, merging, and migration jobs.