Branch policies in SourceCraft

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

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.

Warning

Support for storing configurations for CI/CD, approval rules, and branch policies in a single .src.ci.yaml file at the repository root will soon be discontinued. Use the separate .sourcecraft/ci.yaml, .sourcecraft/review.yaml, and .sourcecraft/branches.yaml files.

For more information, see Setting up a branch policy in a SourceCraft repository.

Warning

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

For more information, see Enabling branch policy bypass for repository administrator.

Sample configuration

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.

Branch policy schema in JSON format

"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",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "prevent_force_push",
          "prevent_non_pr_changes",
          "prevent_all_changes",
          "prevent_deletion",
          "prevent_creation"
        ]
      }
    },
    "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"
  ]
}

Was the article helpful?

Approval rules

Quotas and limits