Skip to main content
Designer uses branching for version control. We recommend that you develop pipelines (both new pipelines and updates to existing pipelines) in Designer on named development branches, rather than the main branch. Not added a project yet? Read Add project.
Choose an appropriate branching strategy for your team based on your development workflow, team size, and collaboration preferences:
  • For teams of three or more, a multi-branch strategy like feature branching is recommended. This allows developers to work on individual features in isolation from the main branch. It is particularly useful when multiple developers are working on different aspects of a project simultaneously.
  • For smaller teams, consider a trunk-based development strategy—a more streamlined approach to version control that prioritizes simplicity and speed. This workflow is suitable for teams focusing on continuous delivery and rapid iteration. The main branch is kept in a deployable state at all times, ensuring that the latest changes are always ready for production.
For more information, read our Unlocking Data Productivity DataOps guide.

​
What is a branch?

A branch is a named pointer to a specific commit in your project’s history—it isn’t a duplicate of your files. When you create a branch, it starts by pointing to the same commit as the branch you created it from, so its contents are identical to that branch at that moment. As you make changes and commit them, your new branch’s pointer moves to include those commits, while the branch you created it from stays exactly where it was. This is why creating a branch is instant, even in a large project—nothing is duplicated, only a new pointer is added. For a deeper explanation of how Git branches work under the hood, read Git Branching - Branches in a Nutshell from the official Git documentation.

​
Local and remote branches

A branch can exist in two places. Knowing the difference helps you understand what’s private to you and what’s shared with your team:
  • A remote branch lives in your Git repository (for example, GitHub, GitLab, Bitbucket, Azure DevOps, or Maia Hosted Git). Remote branches are shared—anyone with access to the repository can see them and work on them.
  • A local branch exists only in your own Maia workspace. A local branch is visible only to you until you push it. Pushing a branch for the first time creates it on the remote repository and makes it available to your collaborators.
When you create a branch in Maia, it starts as a local branch. Your work stays private until you’re ready to share it, so you can experiment freely without affecting anyone else. A branch can exist locally only, on the remote only, or in both places at once. Your Branches list shows all of them. Branches created directly in your Git provider are remote branches. These appear automatically in your Branches list—you don’t need to recreate them manually in Maia before you can use them.

​
Add new branch

  1. In the left navigation, click the Projects icon.
  2. Select your project.
  3. Navigate to the Branches tab.
  4. Click Add branch.
Click Create to add the new branch, or click the X icon to cancel.
There is no limit to the number of branches you can create in a project. However, we recommend that you delete branches that are no longer needed to keep your project organized.
Locate your new branch in the Branches list and click it to redirect to Designer.
By default, a new branch is created as a local branch—it exists only in your workspace until you push it. Pushing for the first time creates the branch on your remote repository and makes it available to your collaborators. To push the branch as soon as it’s created, select Push new branch to remote in the Add branch dialog.

​
View and manage branches

To view the branches in your project:
  1. In the left navigation, click the Projects icon.
  2. Select your project.
  3. Navigate to the Branches tab.
Enter a branch name in the search box to find it. Select Your branches or All from the filter drop-down to show the branches you want. Click the view-toggle icons to switch between list and grid view. The list includes every branch in your project. Click the column headers to sort the list by Name or Last accessed. To change the default environment of a branch:
  1. Click the three dots … for that branch and click Edit branch details.
  2. In the Default environment drop-down menu, select the new default environment for the branch.
Linking a default environment to a branch is optional. A branch’s default environment is a convenience that Designer pre-selects when you open the branch—it’s no longer required, and a branch can have no environment linked at all. When you open a branch in Designer, you can switch to a different environment for your session using the environment drop-down. Switching the environment in Designer doesn’t change the branch’s linked default—the Branches tab is the only place to change that.

​
Delete a branch

You can delete any branch except the default branch (usually main).
  1. In the left navigation, click the Projects icon.
  2. Select your project.
  3. Navigate to the Branches tab.
  4. Click the three dots … for the branch you want to delete and select Delete branch.
  5. If the branch exists on the remote, select what you want to delete:
    • Delete local copy—removes your copy of the branch from Maia but leaves the remote branch in place. You can restore your copy later by pulling the branch again, but only work that was already pushed comes back—any commits or changes you hadn’t pushed are permanently lost.
    • Delete from the remote repository—removes the branch from your Git repository for everyone with access to it. Your local copy, if you have one, is kept.
    • Delete from local and remote—removes both your local copy and the remote branch.
    When more than one person has a local copy of the branch, select Delete for everyone to also delete the branch from other users’ Branches list. This checkbox is cleared by default. Use it to stop a deleted branch from reappearing in the list because a collaborator still holds a local copy. For a branch that exists only locally—one you’ve never pushed—there’s no remote copy to fall back on. There’s nothing to choose: Maia asks you to confirm, and deleting it permanently removes the branch and all the work on it.
  6. Confirm the deletion, then click Delete branch. For an option that can’t be undone, you’re asked to type the branch name before you can continue.
Take care when deleting branches. Deleting from the remote removes the branch for everyone with access to the repository and can’t be undone. Deleting your local copy discards any changes you haven’t pushed. A branch that exists only locally has no remote copy to restore from, so deleting it removes the branch and all its work for good. Before you delete, make sure any work you want to keep has been pushed or merged into another branch.
A branch name is only free to reuse once both versions of the branch are deleted—your local copy and the remote branch. If you delete just your local copy, the remote branch still holds the name.

​
Branch protection

Enforcing branch protection rules is highly recommended, especially for your main branch or your default branch. This ensures that only approved changes are pushed or merged into your production branch. Maia’s integration with supported Git providers uses OAuth 2.0. This means that any branch protection rules or permissions that apply to a user will be honored in Maia. To set up branch protection rules in your Git provider, read the documentation below: