---
metadata:
  - name: generator
    content: Diplodoc Platform v5.57.3
alternate:
  - https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/org-config.md
  - https://sourcecraft.dev/portal/docs/ru/sourcecraft/operations/org-config.md
  - href: en/sourcecraft/operations/org-config.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
title: Setting up approval rules and branch policies at the organization level in SourceCraft
description: Follow this guide to set up approval rules and branch policies common for all repositories in an organization via the `.sourcecraft` repo.
---
> **Documentation Index:** Fetch the complete configuration index at https://sourcecraft.dev/portal/docs/en/llms.txt


# Setting up approval rules and branch policies at the organization level in SourceCraft

You can use a dedicated `.sourcecraft` repository to manage the general [approval rules](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/code-review.md) and [branch policies](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/branch-policies.md) for all repositories in an [organization](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#org).

For more information, see [Approval rules and branch policies at the organization level in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/org-config.md).


## Creating the .sourcecraft repository {#create-repo}

To [create](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/repo-create.md) the `.sourcecraft` repository to manage approval rules and branch policies in an organization:

{% list tabs group=instructions %}

- SourceCraft UI {#src}

  1. Open the SourceCraft [home page](https://sourcecraft.dev).
  1. In the left-hand panel, click ![image](../../_assets/console-icons/plus.svg) **Create repository**.
  1. In the window that opens, select **Blank repository**.
  1. In the **Name** field, specify `.sourcecraft`.
  1. Click **Create repository**.

  {% note info %}

  You can make the `.sourcecraft` repository public, internal, or private: the configuration will still apply to all repositories in the organization.

  {% endnote %}

{% endlist %}


## Setting up approval rules for an organization {#configure-code-review}

To set up unified approval rules for all repositories in an organization:

{% list tabs group=instructions %}

- SourceCraft UI {#src}

  1. Open the SourceCraft [home page](https://sourcecraft.dev).
  1. On the ![image](../../_assets/console-icons/house.svg) **Home** tab, navigate to ![image](../../_assets/console-icons/layout-tabs.svg) **Your craftspace** → ![image](../../_assets/console-icons/archive.svg) **Repositories**.
  1. Select the `.sourcecraft` repository.
  1. Under ![image](../../_assets/console-icons/code.svg) **Code** on the repository page, go to ![image](../../_assets/console-icons/archive.svg) **Overview**.
  1. Select the branch for editing.
  1. Above the list of files in the branch, click ![image](../../_assets/console-icons/square-plus.svg).
  1. Select ![image](../../_assets/console-icons/file.svg) **File**.
  1. In the window that opens, enter `.sourcecraft/review.yaml` as the file name and click **Create file**.
  1. In the `.sourcecraft/review.yaml` file, describe the approval rules as follows:

      <!-- source: en/_includes/sourcecraft/code-review-config.md -->
      ```yaml
      codereview: 
        need_ships: 1 # Required number of approvals from reviewers
        ignore_self_ship: false # Ignore approvals from the pull request author
        ignore_non_reviewers_block: false # Ignore pull request blocking from non-reviewers
        auto_assign: true # Automatically assign reviewers
        disable_trust: true # Disallow the Trust resolution for pull requests
        rules:
          - patterns:
              - "**" # Repository path pattern
            reviewers:
              usernames: 
                - "<user_name>" # List of reviewers
              assign: 1 # Number of automatically assigned reviewers
              need_ships: 1 # Required number of approvals from reviewers
              ignore_self_ship: false # Ignore approvals from the pull request author
      ```
      <!-- endsource: en/_includes/sourcecraft/code-review-config.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 -->

      The syntax of organization-level settings is identical to that of repository-level settings.

  1. <!-- source: en/_includes/sourcecraft/review-patterns.md -->
     Under `patterns`, specify the repository paths for your approval rules as follows:

     * `"**"`: Apply the rule to the entire repository.
     * `"src/**"`: Apply the rule only to the `src` directory.
     * `"!docs/**"`: Do not apply the rule to the `docs` directory.

     You can list multiple patterns one by one, like this:

     ```yaml
     - patterns:
       - "**"
       - "!docs/**"
     ```

     This way, the rule will apply to any changes in your repository except those in the `docs` directory.

     {% note tip %}

     When using multiple patterns, list the `"**"` pattern first.

     {% endnote %}
     <!-- endsource: en/_includes/sourcecraft/review-patterns.md -->
  1. In the top-right corner, click **Commit changes**.
  1. In the window that opens, configure the procedure for changes:
      * In the **Commit message** field, give a comment that will describe the changes you make.
      * Under **Commit branch**, select the default main branch.
      * Under **After commit action**, select `Just commit`.
  1. Confirm your changes.

- Command line {#cli}

  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. Create the `.sourcecraft/review.yaml` file with the approval rule configuration:

      ```bash
      nano .sourcecraft/review.yaml
      ```

  1. Use the following file structure:

      <!-- source: en/_includes/sourcecraft/code-review-config.md -->
      ```yaml
      codereview: 
        need_ships: 1 # Required number of approvals from reviewers
        ignore_self_ship: false # Ignore approvals from the pull request author
        ignore_non_reviewers_block: false # Ignore pull request blocking from non-reviewers
        auto_assign: true # Automatically assign reviewers
        disable_trust: true # Disallow the Trust resolution for pull requests
        rules:
          - patterns:
              - "**" # Repository path pattern
            reviewers:
              usernames: 
                - "<user_name>" # List of reviewers
              assign: 1 # Number of automatically assigned reviewers
              need_ships: 1 # Required number of approvals from reviewers
              ignore_self_ship: false # Ignore approvals from the pull request author
      ```
      <!-- endsource: en/_includes/sourcecraft/code-review-config.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 -->

      The syntax of organization-level settings is identical to that of repository-level settings.

  1. <!-- source: en/_includes/sourcecraft/review-patterns.md -->
     Under `patterns`, specify the repository paths for your approval rules as follows:

     * `"**"`: Apply the rule to the entire repository.
     * `"src/**"`: Apply the rule only to the `src` directory.
     * `"!docs/**"`: Do not apply the rule to the `docs` directory.

     You can list multiple patterns one by one, like this:

     ```yaml
     - patterns:
       - "**"
       - "!docs/**"
     ```

     This way, the rule will apply to any changes in your repository except those in the `docs` directory.

     {% note tip %}

     When using multiple patterns, list the `"**"` pattern first.

     {% endnote %}
     <!-- endsource: en/_includes/sourcecraft/review-patterns.md -->
  1. Add the configuration file to the `git` index, commit, and push the changes to the default main branch:

      ```bash
      git add .sourcecraft/review.yaml
      git commit -m "Added file with organization approval rules"
      git push -u origin <main_branch_name>
      ```

{% endlist %}

## Setting up branch policies for an organization {#configure-branch-policies}

To set up unified branch policies for all repositories in an organization:

{% list tabs group=instructions %}

- SourceCraft UI {#src}

  1. Open the SourceCraft [home page](https://sourcecraft.dev).
  1. On the ![image](../../_assets/console-icons/house.svg) **Home** tab, navigate to ![image](../../_assets/console-icons/layout-tabs.svg) **Your craftspace** → ![image](../../_assets/console-icons/archive.svg) **Repositories**.
  1. Select the `.sourcecraft` repository.
  1. Under ![image](../../_assets/console-icons/code.svg) **Code** on the repository page, go to ![image](../../_assets/console-icons/archive.svg) **Overview**.
  1. Select the branch for editing.
  1. Above the list of files in the branch, click ![image](../../_assets/console-icons/square-plus.svg).
  1. Select ![image](../../_assets/console-icons/file.svg) **File**.
  1. In the window that opens, enter `.sourcecraft/branches.yaml` as the file name and click **Create file**.
  1. In the `.sourcecraft/branches.yaml` file, describe the branch policies 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 -->

      The syntax of organization-level settings is identical to that of repository-level settings.

      <!-- 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. In the top-right corner, click **Commit changes**.
  1. In the window that opens, configure the procedure for changes:
      * In the **Commit message** field, give a comment that will describe the changes you make.
      * Under **Commit branch**, select the default main branch.
      * Under **After commit action**, select `Just commit`.
  1. Confirm your changes.

- Command line {#cli}

  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. Create the `.sourcecraft/branches.yaml` file with the branch policy configuration:

      ```bash
      nano .sourcecraft/branches.yaml
      ```

  1. Use the following file structure:

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

      The syntax of organization-level settings is identical to that of repository-level settings.

      <!-- 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 configuration file to the `git` index, commit, and push the changes:

      ```bash
      git add .sourcecraft/branches.yaml
      git commit -m "Added file with organization branch policies"
      git push -u origin <main_branch_name>
      ```

{% endlist %}


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

* [Approval rules and branch policies at the organization level in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/org-config.md)
* [Approval rules in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/code-review.md)
* [Branch policies in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/branch-policies.md)
* [Setting up approval rules in a SourceCraft repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/code-review.md)
* [Setting up a branch policy in a SourceCraft repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/branch-policies.md)