---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.2
alternate:
  - https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/branch-policies.md
  - https://sourcecraft.dev/portal/docs/ru/sourcecraft/operations/branch-policies.md
  - href: en/sourcecraft/operations/branch-policies.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
title: Setting up a branch policy in a SourceCraft repository
description: How to set up branch policies in your SourceCraft repository to manage merges and protect important branches.
---
> **Documentation Index:** Fetch the complete configuration index at https://sourcecraft.dev/portal/docs/en/llms.txt


# Setting up a branch policy in a SourceCraft repository

<!-- source: en/_includes/sourcecraft/configuration-tip.md -->
{% note tip %}

You can set up and view repository configurations in the SourceCraft interface under ![image](../../_assets/console-icons/gear.svg) **Repository settings** in the ![image](../../_assets/console-icons/nut-hex.svg) **Configurations** section. Learn more in [this article](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/configuration-edit.md).

{% endnote %}
<!-- endsource: en/_includes/sourcecraft/configuration-tip.md -->

<!-- source: en/_includes/sourcecraft/branch-policies-intro.md -->
_Branch policies_ are rules and restrictions that apply to specific branches and tags in a [repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#repos). With policies, you can manage changes, implement code reviews, enforce proper naming and conditions for creating branches and tags, and protect branches from accidental commits or direct pushes.
<!-- endsource: en/_includes/sourcecraft/branch-policies-intro.md -->

For more information, see [Branch policies in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/branch-policies.md).

<!-- source: en/_includes/sourcecraft/branch-policies-config.md -->
You specify the policy configuration for a particular repository and store it in the `.sourcecraft/branches.yaml` file. A configuration stored in the main branch, e.g., `master` or `main`, applies to the entire repository. You can also set the [configuration at the SourceCraft organization level](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/org-config.md).

The general policy configuration format in `.sourcecraft/branches.yaml` is as follows:

<!-- source: en/_includes/sourcecraft/branch-policies-config-template.md -->
```yaml
branch_protection:
  policies:
    - target: <protected_resource_type>
      matches: "<filter>"
      message: "<message_to_user_on_trigger>"
      rules:
        - <rule_1>
        - <rule_2>
```

Where:

* `target`: Protected resource type. This is a required setting. The possible values are:
  * `default_branch`: Main branch, such as `master` or `main`.
  * `branch`: Branch.
  * `tag`: Tag.

* `matches`: Filter or list of filters by protected resource name. This is a required parameter for `target: branch` and `target: tag`. 
* `message`: Message the user will get when the policy is triggered. This is a required setting.
* `rules`: Rule or list of rules to apply to the protected resource. This is a required setting. The possible values are:
  * `prevent_force_push`: Prevent rewriting the branch commit history (`force push` operations). 
  * `prevent_non_pr_changes`: Prevent direct edits to the branch (`push` operations); edits must be submitted through a [pull request](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#pr).
  * `prevent_all_changes`: Prevent any actions with the branch or tag.

      <!-- source: en/_includes/sourcecraft/branch-policies-deprecated-rule.md -->
      {% note warning %}

      The `prevent_all_changes` rule is deprecated. Instead, use the `prevent_creation` and `prevent_update` rules together.

      {% endnote %}
      <!-- endsource: en/_includes/sourcecraft/branch-policies-deprecated-rule.md -->

  * `prevent_deletion`: Prevent deletion of a branch or tag.
  * `prevent_creation`: Prevent creating a branch or tag.
  * `prevent_update`: Prevent branch or tag updates after creation (prohibits `push`, `force push`, delete, and merge operations via a pull request).
<!-- endsource: en/_includes/sourcecraft/branch-policies-config-template.md -->
<!-- endsource: en/_includes/sourcecraft/branch-policies-config.md -->

For the full schema, see [Branch policy schema in JSON format](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/branch-policies.md#json-schema).

To set up branch policies in a repository, follow these steps: 
1. Clone the repository:

    <!-- source: en/_includes/sourcecraft/clone-repo-workflow.md -->
    1. [Install Git](https://git-scm.com/downloads).
    1. Open the SourceCraft [home page](https://sourcecraft.dev).
    1. On the ![image](../../_assets/console-icons/house.svg) **Home** tab, under ![image](../../_assets/console-icons/layout-tabs.svg) **Your craftspace**, navigate to ![image](../../_assets/console-icons/archive.svg) **Repositories** and select your repository.

        Also, you can open any public repository.

    1. In the top-right corner of the repository page, click ![image](../../_assets/console-icons/chevron-down-wide.svg) **Clone**.
    1. From the **HTTPS** or **SSH** field, copy the ![image](../../_assets/console-icons/copy.svg) repository cloning link.

        Depending on the cloning connection protocol, different domains are used:

        #|
        || **Protocol** | **Domain** | **Cloning link** ||
        || HTTPS | `git.sourcecraft.dev` | `https://git@git.sourcecraft.dev/<organization_slug>/<repository_slug>.git` ||
        || SSH | `ssh.sourcecraft.dev` | `ssh://ssh.sourcecraft.dev/<organization_slug>/<repository_slug>.git` ||
        |#

    1. In the terminal, run this command:

        ```bash
        git clone <link_for_cloning_repository>
        ```

        {% cut "Example of a command for cloning a repository with SourceCraft documentation" %}

        ```bash
        git clone https://git@git.sourcecraft.dev/sourcecraft/documentation.git
        ```

        {% endcut %}

        <!-- source: en/_includes/sourcecraft/private-repo-clone-note.md -->
        {% note warning %}

        To clone a [private or internal repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#repos), authenticate with a [personal access token (PAT)](https://sourcecraft.dev/portal/docs/en/sourcecraft/security/pat.md) or [SSH key](https://sourcecraft.dev/portal/docs/en/sourcecraft/security/ssh.md).

        {% endnote %}
        <!-- endsource: en/_includes/sourcecraft/private-repo-clone-note.md -->

    1. Go to your cloned repository:
        
        ```bash
        cd <repository_name>
        ```
    <!-- endsource: en/_includes/sourcecraft/clone-repo-workflow.md -->

1. Generate a branch policy configuration file named `.sourcecraft/branches.yaml`, for example:

    <!-- source: en/_includes/sourcecraft/branch-policies-example.md -->
    ```yaml
    branch_protection:
      policies:
        ## Preventing commit history rewrites, edits without 
        ## a pull request, and deletion of the main branch
        - target: default_branch
          message: "Direct push into main branch is forbidden, create PR first"
          rules:
            - prevent_force_push
            - prevent_non_pr_changes
            - prevent_deletion

        ## Preventing the creation of branches with names that match filters
        - target: branch
          matches: ["**", "!OO-**/**", "!hotfix/**", "!chore/**", "!release/**"]
          message: "Please use proper branch naming"
          rules:
            - prevent_creation

        ## Preventing the creation of tags with names that match filters
        - target: tag
          matches: "gitcore-**"
          message: "Manual tag creation is forbidden, please use Releaser"
          rules:
            - prevent_creation
    ```

    See also the branch policy example in the [test-serverless-cube SourceCraft repository](https://sourcecraft.dev/mikhail-bondarevsky/test-serverless-cube/browse/.src.ci.yaml?rev=master).
    <!-- endsource: en/_includes/sourcecraft/branch-policies-example.md -->

    <!-- source: en/_includes/sourcecraft/wildcard-pattern-tip.md -->
    {% note tip %}

    For group filtering, we recommend to use the `**` pattern because the simple `*` pattern will not give you a match in expressions with `/`.

    {% endnote %}
    <!-- endsource: en/_includes/sourcecraft/wildcard-pattern-tip.md -->

    For more information on path filter syntax and rules, see [this section](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/filters-by-paths.md).

1. Add the branch policy configuration file to the `git` index, commit, and push the changes to the remote branch named `main`:

    ```bash
    git add .sourcecraft/branches.yaml
    git commit -m "Added branch policies configuration"
    git push -u origin main
    ```

1. To test if your branch policy works, make changes to the files in the main branch, commit, and try pushing your changes to a remote repository:

    ```bash
    git add .
    git commit -m "Test changes"
    git push -u origin main
    ```

    This will return an error saying `Direct push into main branch is forbidden, create PR first`.

## Setting up automatic branch deletion post-merge {#branch-cleanup}

You can set up automatic deletion of pull request source branch after its merge with the target branch. For more information, see [Automatic branch deletion post-merge](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/branch-policies.md#branch-cleanup).

To set up automatic branch deletion:

1. Clone the repository:

    <!-- source: en/_includes/sourcecraft/clone-repo-workflow.md -->
    1. [Install Git](https://git-scm.com/downloads).
    1. Open the SourceCraft [home page](https://sourcecraft.dev).
    1. On the ![image](../../_assets/console-icons/house.svg) **Home** tab, under ![image](../../_assets/console-icons/layout-tabs.svg) **Your craftspace**, navigate to ![image](../../_assets/console-icons/archive.svg) **Repositories** and select your repository.

        Also, you can open any public repository.

    1. In the top-right corner of the repository page, click ![image](../../_assets/console-icons/chevron-down-wide.svg) **Clone**.
    1. From the **HTTPS** or **SSH** field, copy the ![image](../../_assets/console-icons/copy.svg) repository cloning link.

        Depending on the cloning connection protocol, different domains are used:

        #|
        || **Protocol** | **Domain** | **Cloning link** ||
        || HTTPS | `git.sourcecraft.dev` | `https://git@git.sourcecraft.dev/<organization_slug>/<repository_slug>.git` ||
        || SSH | `ssh.sourcecraft.dev` | `ssh://ssh.sourcecraft.dev/<organization_slug>/<repository_slug>.git` ||
        |#

    1. In the terminal, run this command:

        ```bash
        git clone <link_for_cloning_repository>
        ```

        {% cut "Example of a command for cloning a repository with SourceCraft documentation" %}

        ```bash
        git clone https://git@git.sourcecraft.dev/sourcecraft/documentation.git
        ```

        {% endcut %}

        <!-- source: en/_includes/sourcecraft/private-repo-clone-note.md -->
        {% note warning %}

        To clone a [private or internal repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#repos), authenticate with a [personal access token (PAT)](https://sourcecraft.dev/portal/docs/en/sourcecraft/security/pat.md) or [SSH key](https://sourcecraft.dev/portal/docs/en/sourcecraft/security/ssh.md).

        {% endnote %}
        <!-- endsource: en/_includes/sourcecraft/private-repo-clone-note.md -->

    1. Go to your cloned repository:
        
        ```bash
        cd <repository_name>
        ```
    <!-- endsource: en/_includes/sourcecraft/clone-repo-workflow.md -->

1. In the `.sourcecraft/branches.yaml` file, add a section named `pull_request.branch_cleanup` and, in `matches`, specify [path filters](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/filters-by-paths.md) for branches subject to automatic deletion. Here is an example:

    ```yaml
    pull_request:
      branch_cleanup:
        matches: ["**", "!hotfix/**", "!chore/**", "!release/**"]
    ```

    In this example, automatic deletion is enabled for all branches except `hotfix/**`, `chore/**`, and `release/**`.

    <!-- source: en/_includes/sourcecraft/wildcard-pattern-tip.md -->
    {% note tip %}

    For group filtering, we recommend to use the `**` pattern because the simple `*` pattern will not give you a match in expressions with `/`.

    {% endnote %}
    <!-- endsource: en/_includes/sourcecraft/wildcard-pattern-tip.md -->

1. Add the modified configuration file to the `git` index, then commit and push the changes to the remote branch named `main`:

    ```bash
    git add .sourcecraft/branches.yaml
    git commit -m "Configured automatic branch cleanup"
    git push -u origin main
    ```

{% note tip %}

You can override the behavior set in the `.sourcecraft/branches.yaml` file for a specific pull request by using the **Delete source branch when merged** option in the **Merge settings** section. For more information, see [Working with pull requests in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/pr-work.md).

{% endnote %}

## Enabling branch policy bypass for repository administrator {#bypass}

<!-- source: en/_includes/sourcecraft/branch-policies-bypass.md -->
{% note warning %}

Only users with the `Repository admin` [role](https://sourcecraft.dev/portal/docs/en/sourcecraft/security/index.md#src-repositories-admin) can override the branch policy rules, e.g., to update the configuration in `.sourcecraft/branches.yaml`.

{% endnote %}
<!-- endsource: en/_includes/sourcecraft/branch-policies-bypass.md -->

1. Open the SourceCraft [home page](https://sourcecraft.dev).
1. On the ![image](../../_assets/console-icons/house.svg) **Home** tab, under ![image](../../_assets/console-icons/layout-tabs.svg) **Your craftspace**, navigate to ![image](../../_assets/console-icons/archive.svg) **Repositories**.
1. Select a repository.
1. Under ![image](../../_assets/console-icons/gear.svg) **Repository settings** on the repository page, go to ![image](../../_assets/console-icons/circle-exclamation.svg) **General**.
1. Under **Branch protection policy**, turn on the **Enable redefinition** option.
1. Click **Update settings**.

#### Useful links {#see-also}

* [Branch policies in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/branch-policies.md)
* [Approval rules in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/code-review.md)
* [Continuous integration and continuous deployment in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md)
* [Configuring CI/CD in a SourceCraft repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/ci-cd.md)
* [Setting up approval rules in a SourceCraft repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/code-review.md)
* [Setting up approval rules and branch policies at the organization level in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/org-config.md)