Setting up a branch policy in a SourceCraft repository

Branch policies are rules and restrictions that apply to specific branches and tags in a repository. 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.

For more information, see Branch policies in SourceCraft.

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.

The general policy configuration format in .sourcecraft/branches.yaml is 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 parameter. 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 parameter.
• rules: Rule or list of rules to apply to the protected resource. This is a required parameter. The possible values are:
  • prevent_force_push: Prevent rewriting the branch commit history (force push operations).
  • prevent_non_pr_changes: Prevent direct changes to the branch (push operations); changes must be submitted through pull requests.
  • 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.

For the full schema, see Branch policy schema in JSON format.

To set up branch policies in a repository, follow these steps:

1. Clone the repository:

   1. Install Git.

   2. Open the SourceCraft home page.

   3. On the Home tab, navigate to Repositories and select a 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. Generate a branch policy configuration file named .sourcecraft/branches.yaml, for example:

   branch_protection:
     policies:
       ## Preventing commit history rewrites, no-PR changes, 
       ## 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.

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

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

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

   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.

Enabling branch policy bypass for repository administrator

1. Open the SourceCraft home page.
2. On the Home tab, navigate to Repositories.
3. Select a repository.
4. Under Settings on the repository page, go to General.
5. Under Branch protection policy, turn on the Enable redefinition option.
6. Click Update settings.

See also

• Branch policies in SourceCraft
• Approval rules in SourceCraft
• Continuous integration and continuous deployment in SourceCraft
• Configuring CI/CD in a SourceCraft repository
• Setting up approval rules in a SourceCraft repository