---
title: "Create a branch restriction rule"
method: POST
path: "/repositories/{workspace}/{repo_slug}/branch-restrictions"
tags: ["Branch restrictions"]
---

# Create a branch restriction rule

`POST /repositories/{workspace}/{repo_slug}/branch-restrictions`

Creates a new branch restriction rule for a repository.

`kind` describes what will be restricted. Allowed values include:
`push`, `force`, `delete`, `restrict_merges`, `require_tasks_to_be_completed`,
`require_approvals_to_merge`, `require_default_reviewer_approvals_to_merge`,
`require_no_changes_requested`, `require_passing_builds_to_merge`, `require_commits_behind`,
`reset_pullrequest_approvals_on_change`, `smart_reset_pullrequest_approvals`,
`reset_pullrequest_changes_requested_on_change`, `require_all_dependencies_merged`,
`enforce_merge_checks`, and `allow_auto_merge_when_builds_pass`.

Different kinds of branch restrictions have different requirements:

* `push` and `restrict_merges` require `users` and `groups` to be
  specified. Empty lists are allowed, in which case permission is
  denied for everybody.

The restriction applies to all branches that match. There are
two ways to match a branch. It is configured in `branch_match_kind`:

1. `glob`: Matches a branch against the `pattern`. A `'*'` in
   `pattern` will expand to match zero or more characters, and every
   other character matches itself. For example, `'foo*'` will match
   `'foo'` and `'foobar'`, but not `'barfoo'`. `'*'` will match all
   branches.
2. `branching_model`: Matches a branch against the repository's
   branching model. The `branch_type` controls the type of branch
   to match. Allowed values include: `production`, `development`,
   `bugfix`, `release`, `feature` and `hotfix`.

The combination of `kind` and match must be unique. This means that
two `glob` restrictions in a repository cannot have the same `kind` and
`pattern`. Additionally, two `branching_model` restrictions in a
repository cannot have the same `kind` and `branch_type`.

`users` and `groups` are lists of users and groups that are except from
the restriction. They can only be configured in `push` and
`restrict_merges` restrictions. The `push` restriction stops a user
pushing to matching branches unless that user is in `users` or is a
member of a group in `groups`. The `restrict_merges` stops a user
merging pull requests to matching branches unless that user is in
`users` or is a member of a group in `groups`. Adding new users or
groups to an existing restriction should be done via `PUT`.

Note that branch restrictions with overlapping matchers is allowed,
but the resulting behavior may be surprising.

## Request body

- Branchrestriction — A branch restriction rule.
  - `type` string, required
  - `links` object
    - `self` object — A link to a resource related to this object.
      - `href` string, uri
      - `name` string
  - `id` integer — The branch restriction status' id.
  - `kind` 'push' | 'delete' | 'force' | 'restrict_merges' | 'require_tasks_to_be_completed' | 'require_approvals_to_merge' | 'require_review_group_approvals_to_merge' | 'require_default_reviewer_approvals_to_merge' | 'require_no_changes_requested' | 'require_passing_builds_to_merge' | 'require_commits_behind' | 'reset_pullrequest_approvals_on_change' | 'smart_reset_pullrequest_approvals' | 'reset_pullrequest_changes_requested_on_change' | 'require_all_dependencies_merged' | 'enforce_merge_checks' | 'allow_auto_merge_when_builds_pass' | 'require_all_comments_resolved', required — The type of restriction that is being applied.
  - `branch_match_kind` 'branching_model' | 'glob', required — Indicates how the restriction is matched against a branch. The default is `glob`.
  - `branch_type` 'feature' | 'bugfix' | 'release' | 'hotfix' | 'development' | 'production' — Apply the restriction to branches of this type. Active when `branch_match_kind` is `branching_model`. The branch type will be calculated using the branching model configured for the repository.
  - `pattern` string, required — Apply the restriction to branches that match this pattern. Active when `branch_match_kind` is `glob`. Will be empty when `branch_match_kind` is `branching_model`.
  - `value` integer — Value with kind-specific semantics: * `require_approvals_to_merge` uses it to require a minimum number of approvals on a PR. * `require_default_reviewer_approvals_to_merge` uses it to require a minimum number of approvals from default reviewers on a PR. * `require_passing_builds_to_merge` uses it to require a minimum number of passing builds. * `require_commits_behind` uses it to require the current branch is up to a maximum number of commits behind it destination.
  - `users` Account[]
    - `type` string, required
    - `links` AccountLinks — Links related to an Account.
      - `avatar` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
    - `created_on` string, date-time
    - `display_name` string
    - `uuid` string
  - `groups` Group[]
    - `type` string, required
    - `links` object
      - `self` object — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
      - `html` object — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
    - `owner` Account — An account object.
      - `type` string, required
      - `links` AccountLinks — Links related to an Account.
        - `avatar` Link — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
      - `created_on` string, date-time
      - `display_name` string
      - `uuid` string
    - `workspace` Workspace — A Bitbucket workspace. Workspaces are used to organize repositories.
      - `type` string, required
      - `links` object
        - `avatar` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
        - `html` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
        - `members` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
        - `owners` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
        - `projects` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
        - `repositories` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
        - `snippets` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
        - `self` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
      - `uuid` string — The workspace's immutable id.
      - `name` string — The name of the workspace.
      - `slug` string — The short label that identifies this workspace.
      - `is_private` boolean — Indicates whether the workspace is publicly accessible, or whether it is private to the members and consequently only visible to members.
      - `is_personal` boolean — Indicates whether the workspace belongs to an individual user.
      - `is_privacy_enforced` boolean — Indicates whether the workspace enforces private content, or whether it allows public content.
      - `forking_mode` 'allow_forks' | 'internal_only' — Controls the rules for forking repositories within this workspace. * **allow_forks**: unrestricted forking * **internal_only**: prevents forking of private repositories outside the workspace or to public repositories
      - `created_on` string, date-time
      - `updated_on` string, date-time
    - `name` string
    - `slug` string — The "sluggified" version of the group's name. This contains only ASCII characters and can therefore be slightly different than the name
    - `full_slug` string — The concatenation of the workspace's slug and the group's slug, separated with a colon (e.g. `acme:developers`)

## Response `201`

A paginated list of branch restrictions

- Branchrestriction — A branch restriction rule.
  - `type` string, required
  - `links` object
    - `self` object — A link to a resource related to this object.
      - `href` string, uri
      - `name` string
  - `id` integer — The branch restriction status' id.
  - `kind` 'push' | 'delete' | 'force' | 'restrict_merges' | 'require_tasks_to_be_completed' | 'require_approvals_to_merge' | 'require_review_group_approvals_to_merge' | 'require_default_reviewer_approvals_to_merge' | 'require_no_changes_requested' | 'require_passing_builds_to_merge' | 'require_commits_behind' | 'reset_pullrequest_approvals_on_change' | 'smart_reset_pullrequest_approvals' | 'reset_pullrequest_changes_requested_on_change' | 'require_all_dependencies_merged' | 'enforce_merge_checks' | 'allow_auto_merge_when_builds_pass' | 'require_all_comments_resolved', required — The type of restriction that is being applied.
  - `branch_match_kind` 'branching_model' | 'glob', required — Indicates how the restriction is matched against a branch. The default is `glob`.
  - `branch_type` 'feature' | 'bugfix' | 'release' | 'hotfix' | 'development' | 'production' — Apply the restriction to branches of this type. Active when `branch_match_kind` is `branching_model`. The branch type will be calculated using the branching model configured for the repository.
  - `pattern` string, required — Apply the restriction to branches that match this pattern. Active when `branch_match_kind` is `glob`. Will be empty when `branch_match_kind` is `branching_model`.
  - `value` integer — Value with kind-specific semantics: * `require_approvals_to_merge` uses it to require a minimum number of approvals on a PR. * `require_default_reviewer_approvals_to_merge` uses it to require a minimum number of approvals from default reviewers on a PR. * `require_passing_builds_to_merge` uses it to require a minimum number of passing builds. * `require_commits_behind` uses it to require the current branch is up to a maximum number of commits behind it destination.
  - `users` Account[]
    - `type` string, required
    - `links` AccountLinks — Links related to an Account.
      - `avatar` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
    - `created_on` string, date-time
    - `display_name` string
    - `uuid` string
  - `groups` Group[]
    - `type` string, required
    - `links` object
      - `self` object — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
      - `html` object — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
    - `owner` Account — An account object.
      - `type` string, required
      - `links` AccountLinks — Links related to an Account.
        - `avatar` Link — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
      - `created_on` string, date-time
      - `display_name` string
      - `uuid` string
    - `workspace` Workspace — A Bitbucket workspace. Workspaces are used to organize repositories.
      - `type` string, required
      - `links` object
        - `avatar` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
        - `html` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
        - `members` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
        - `owners` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
        - `projects` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
        - `repositories` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
        - `snippets` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
        - `self` object — A link to a resource related to this object.
          - `href` string, uri
          - `name` string
      - `uuid` string — The workspace's immutable id.
      - `name` string — The name of the workspace.
      - `slug` string — The short label that identifies this workspace.
      - `is_private` boolean — Indicates whether the workspace is publicly accessible, or whether it is private to the members and consequently only visible to members.
      - `is_personal` boolean — Indicates whether the workspace belongs to an individual user.
      - `is_privacy_enforced` boolean — Indicates whether the workspace enforces private content, or whether it allows public content.
      - `forking_mode` 'allow_forks' | 'internal_only' — Controls the rules for forking repositories within this workspace. * **allow_forks**: unrestricted forking * **internal_only**: prevents forking of private repositories outside the workspace or to public repositories
      - `created_on` string, date-time
      - `updated_on` string, date-time
    - `name` string
    - `slug` string — The "sluggified" version of the group's name. This contains only ASCII characters and can therefore be slightly different than the name
    - `full_slug` string — The concatenation of the workspace's slug and the group's slug, separated with a colon (e.g. `acme:developers`)

## Other responses

- `401` — If the request was not authenticated
- `403` — If the authenticated user does not have admin access to the repository
- `404` — If the repository does not exist

---

[API](https://skmtc.net/bitbucket/apis/bitbucket-api.md) · [All operations](https://skmtc.net/bitbucket/apis/bitbucket-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bitbucket/bitbucket-api/revisions/d98b7da55533/schema)