Setting up a branch policy in a SourceCraft repository

Tip

You can set up and view repository configurations in the SourceCraft interface under Repository settings in the Configurations section. Learn more in this article.

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. You can also set the configuration at the SourceCraft organization level.

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 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.
  
  Warning
  
  The prevent_all_changes rule is deprecated. Instead, use the prevent_creation and prevent_update rules together.
- 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).

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

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

Clone the repository:

Install Git.
Open the SourceCraft home page.
On the Home tab, under Your craftspace, navigate to Repositories and select your repository.

Also, you can open any public repository.
In the top-right corner of the repository page, click Clone.

From the HTTPS or SSH field, copy the 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`

In the terminal, run this command:
```
git clone <link_for_cloning_repository>
```
Example of a command for cloning a repository with SourceCraft documentation
```
git clone https://git@git.sourcecraft.dev/sourcecraft/documentation.git
```
Warning

To clone a private or internal repository, authenticate with a personal access token (PAT) or SSH key.
Go to your cloned repository:
```
cd <repository_name>
```

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

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.

Tip

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

For more information on path filter syntax and rules, see this section.

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

Setting up automatic branch deletion post-merge

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.

To set up automatic branch deletion:

Clone the repository:

Install Git.
Open the SourceCraft home page.
On the Home tab, under Your craftspace, navigate to Repositories and select your repository.

Also, you can open any public repository.
In the top-right corner of the repository page, click Clone.

From the HTTPS or SSH field, copy the 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`

In the terminal, run this command:
```
git clone <link_for_cloning_repository>
```
Example of a command for cloning a repository with SourceCraft documentation
```
git clone https://git@git.sourcecraft.dev/sourcecraft/documentation.git
```
Warning

To clone a private or internal repository, authenticate with a personal access token (PAT) or SSH key.
Go to your cloned repository:
```
cd <repository_name>
```

In the .sourcecraft/branches.yaml file, add a section named pull_request.branch_cleanup and, in matches, specify path filters for branches subject to automatic deletion. Here is an example:
```
pull_request:
  branch_cleanup:
    matches: ["**", "!hotfix/**", "!chore/**", "!release/**"]
```
In this example, automatic deletion is enabled for all branches except hotfix/**, chore/**, and release/**.

Tip

For group filtering, we recommend to use the ** pattern because the simple * pattern will not give you a match in expressions with /.
Add the modified configuration file to the git index, then commit and push the changes to the remote branch named main:
```
git add .sourcecraft/branches.yaml
git commit -m "Configured automatic branch cleanup"
git push -u origin main
```

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.

Enabling branch policy bypass for repository administrator

Warning

Only users with the Repository admin role can override the branch policy rules, e.g., to update the configuration in .sourcecraft/branches.yaml.

Open the SourceCraft home page.
On the Home tab, under Your craftspace, navigate to Repositories.
Select a repository.
Under Repository settings on the repository page, go to General.
Under Branch protection policy, turn on the Enable redefinition option.
Click Update settings.

Useful links

Was the article helpful?

Setting up approval rules

Setting up a configuration at the organization level