---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.2
alternate:
  - https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/branch-policies.md
  - https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/branch-policies.md
  - href: en/sourcecraft/concepts/branch-policies.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
title: Branch policies in SourceCraft
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


# Branch policies in SourceCraft

<!-- 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 example, you can set up a policy so that only reviewed and approved changes are pushed to the main branch. This helps to maintain code stability and quality, make the development process more transparent, and prevent errors.

<!-- 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 more information, see [Setting up a branch policy in a SourceCraft repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/branch-policies.md).

<!-- 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 -->

For more information, see [Enabling branch policy bypass for repository administrator](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/branch-policies.md#bypass).

## Configuration example {#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 -->

<!-- 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 -->

## Automatic branch deletion post-merge {#branch-cleanup}

In the `.sourcecraft/branches.yaml` file, you can configure rules to automatically clean up source branches once a pull request is merged into the target branch. This helps maintain a clean repository and prevents the accumulation of stale branches.

Rules are defined in the `pull_request.branch_cleanup.matches` section using [path filters](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/filters-by-paths.md). For 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/**`.

The configuration in `.sourcecraft/branches.yaml` defines the default behavior at the repository level. However, you can override this setting for an individual pull request using the **Delete source branch when merged** option under **Merge settings**. For more information, see [Working with pull requests in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/pr-work.md).

## Branch policy schema in JSON format {#json-schema}

```json
"branch_protection_policy": {
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "target": {
      "title": "Policy Target",
      "description": "Type of target this policy is applied to",
      "type": "string",
      "enum": [
        "default_branch",
        "branch",
        "tag"
      ]
    },
    "message": {
      "title": "Error message",
      "description": "Custom message that will be displayed if policy is violated",
      "type": "string"
    },
    "rules": {
      "title": "Rules",
      "description": "Set of rules. The 'prevent_all_changes' value is deprecated; use 'prevent_creation' together with 'prevent_update' instead.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "prevent_force_push",
          "prevent_non_pr_changes",
          "prevent_all_changes",
          "prevent_deletion",
          "prevent_creation",
          "prevent_update"
        ]
      }
    },
    "matches": {
      "title": "Glob Match",
      "description": "For tag and branch target, pattern matcher. See globstar patterns for the details",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    }
  },
  "required": [
    "target",
    "message",
    "rules"
  ]
}
```

<!-- 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 -->

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

* [Setting up a branch policy in a SourceCraft repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/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)