> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Branches

export const maia = "Maia";

export const designer = "Designer";

{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](/docs/guides/projects).

<Tip>
  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](https://www.matillion.com/whitePaper/unlocking-data-productivity-data-ops-guide) DataOps guide.
</Tip>

***

## 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 new branch**.

| Property            | Description                                                                                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Branch name         | A unique name for the new branch. Branch names can include letters, numbers, hyphens, underscores, and forward slashes. You can't rename a branch after it has been created. |
| Branch from         | Select which branch to branch *from*, for example, `main`.                                                                                                                   |
| Default environment | Select the environment that this branch will use by default. Not created an environment yet? Read [Add environment](/docs/guides/environments).                              |

Click **Create** to add the new branch, or click **Never mind** to cancel.

Locate your new branch in the **Branches** menu and click it to redirect to {designer}.

<Warning>
  Branches must be created through the **Branches** UI to be used in {designer}. Branches created directly in your external Git provider (such as GitHub, Bitbucket, GitLab, or Azure DevOps) will not automatically appear in {maia}. If you need to work with a branch that was created externally, you must create a branch with the same name in **Branches**.
</Warning>

***

## 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.

Click the column headers to sort the list of branches in your project by **Name** or by **Default environment**.

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.

To delete a branch:

1. Click the three dots **...** for that branch and click **Delete branch**. You cannot delete the `main` branch.
2. In the **Enter branch name** field, type the name of the branch that you want to delete.
3. Click **Delete branch**.

<Warning>
  If you use a Matillion-hosted Git repository, deleted branches *cannot* be recovered. You can reuse the name of a deleted branch for a new branch.
</Warning>

If you use your own Git repository, deleting a branch in {maia} does *not* delete the remote version of the branch. To permanently delete a branch, you also need to delete the remote version via your Git provider. To reuse the name of a deleted branch, you need to delete both versions of the branch.

***

## 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:

* [GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)
* [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops\&tabs=browser)
* [GitLab](https://docs.gitlab.com/user/project/repository/branches/branch_rules/)
* [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/use-branch-permissions/)