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:

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

Servers

https://api.bitbucket.org/2.0

Path parameters

Name	Type	Required	Description
`repo_slug`	String	Yes	This can either be the repository slug or the UUID of the repository, surrounded by curly-braces, for example: `{repository UUID}`.
`workspace`	String	Yes	This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: `{workspace UUID}`.

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Request body fields

Name	Type	Required	Description
`id`	Integer	No	The branch restriction status' id.
`groups[]`	Array	No
`groups[].name`	String	No
`groups[].slug`	String	No	The "sluggified" version of the group's name. This contains only ASCII characters and can therefore be slightly different than the name
`groups[].type`	String	Yes
`groups[].full_slug`	String	No	The concatenation of the workspace's slug and the group's slug, separated with a colon (e.g. `acme:developers`)
`groups[].links`	Object	No
`groups[].links.html`	Object	No	A link to a resource related to this object.
`groups[].links.html.href`	String	No
`groups[].links.html.name`	String	No
`groups[].links.self`	Object	No	A link to a resource related to this object.
`groups[].links.self.href`	String	No
`groups[].links.self.name`	String	No
`type`	String	Yes
`branch_match_kind`	String	Yes	Indicates how the restriction is matched against a branch. The default is `glob`. Valid values: `"branching_model"` `"glob"`
`value`	Integer	No	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.
`kind`	String	Yes	The type of restriction that is being applied. Valid values: `"require_tasks_to_be_completed"` `"require_approvals_to_merge"` `"push"` `"require_no_changes_requested"` `"reset_pullrequest_approvals_on_change"` `"require_all_dependencies_merged"` `"delete"` `"restrict_merges"` `"require_review_group_approvals_to_merge"` `"reset_pullrequest_changes_requested_on_change"` `"force"` `"require_commits_behind"` `"allow_auto_merge_when_builds_pass"` `"require_all_comments_resolved"` `"enforce_merge_checks"` `"require_passing_builds_to_merge"` `"require_default_reviewer_approvals_to_merge"` `"smart_reset_pullrequest_approvals"`
`users[]`	Array	No
`users[].uuid`	String	No
`users[].created_on`	String	No
`users[].type`	String	Yes
`users[].display_name`	String	No
`users[].links`	Object	No	Links related to an Account.
`users[].links.avatar`	Object	No	A link to a resource related to this object.
`users[].links.avatar.href`	String	No
`users[].links.avatar.name`	String	No
`links`	Object	No
`links.self`	Object	No	A link to a resource related to this object.
`links.self.href`	String	No
`links.self.name`	String	No
`pattern`	String	Yes	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`.
`branch_type`	String	No	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. Valid values: `"bugfix"` `"hotfix"` `"release"` `"development"` `"feature"` `"production"`

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.