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 and branch policies for all repositories in an organization.

For more information, see Approval rules and branch policies at the organization level in SourceCraft.

Creating the .sourcecraft repository

To create the .sourcecraft repository to manage approval rules and branch policies in an organization:

  1. Open the SourceCraft home page.
  2. In the left-hand panel, click Create repository.
  3. In the window that opens, select Blank repository.
  4. In the Name field, specify .sourcecraft.
  5. Click Create repository.

Note

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

Setting up approval rules for an organization

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

  1. Open the SourceCraft home page.

  2. On the Home tab, navigate to Your craftspace → Repositories.

  3. Select the .sourcecraft repository.

  4. Under Code on the repository page, go to Overview.

  5. Select the branch for editing.

  6. Above the list of files in the branch, click .

  7. Select File .

  8. In the window that opens, enter .sourcecraft/review.yaml as the file name and click Create file.

  9. In the .sourcecraft/review.yaml file, describe the approval rules as follows:

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

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

  10. 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:

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

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

    Tip

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

  11. In the top-right corner, click Commit changes.

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

  13. Confirm your changes.

  1. Clone the repository:

    1. Install Git.

    2. Open the SourceCraft home page.

    3. On the Home tab, under Your craftspace, navigate to Repositories and select your repository.

    4. In the top-right corner, click Clone.

    5. Depending on your connection method, copy the link for cloning the repository.

    6. In the terminal, run this command:

      git clone <link_for_cloning_repository>

    7. Go to your cloned repository:

      cd <repository_name>

  2. Create the .sourcecraft/review.yaml file with the approval rule configuration:

    nano .sourcecraft/review.yaml

  3. Use the following file structure:

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

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

  4. 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:

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

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

    Tip

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

  5. Add the configuration file to the git index, commit, and push the changes to the default main branch:

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

Setting up branch policies for an organization

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

  1. Open the SourceCraft home page.

  2. On the Home tab, navigate to Your craftspace → Repositories.

  3. Select the .sourcecraft repository.

  4. Under Code on the repository page, go to Overview.

  5. Select the branch for editing.

  6. Above the list of files in the branch, click .

  7. Select File .

  8. In the window that opens, enter .sourcecraft/branches.yaml as the file name and click Create file.

  9. In the .sourcecraft/branches.yaml file, describe the branch policies as follows:

    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.
      • prevent_all_changes: Prevent any actions with the branch or tag.
      • prevent_deletion: Prevent deletion of a branch or tag.
      • prevent_creation: Prevent creating a branch or tag.

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

  10. In the top-right corner, click Commit changes.

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

  12. Confirm your changes.

  1. Clone the repository:

    1. Install Git.

    2. Open the SourceCraft home page.

    3. On the Home tab, under Your craftspace, navigate to Repositories and select your repository.

    4. In the top-right corner, click Clone.

    5. Depending on your connection method, copy the link for cloning the repository.

    6. In the terminal, run this command:

      git clone <link_for_cloning_repository>

    7. Go to your cloned repository:

      cd <repository_name>

  2. Create the .sourcecraft/branches.yaml file with the branch policy configuration:

    nano .sourcecraft/branches.yaml

  3. Use the following file structure:

    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.
      • prevent_all_changes: Prevent any actions with the branch or tag.
      • prevent_deletion: Prevent deletion of a branch or tag.
      • prevent_creation: Prevent creating a branch or tag.

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

  4. Add the configuration file to the git index, commit, and push the changes:

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

See also

Previous
Setting up branch policies
Next
Editing code