Addon
Branch restrictions
Branching model
Commit statuses
Commits
Deployments
Downloads
Issue tracker
Pipelines
Projects
Pullrequests
Refs
Reports
Repositories
Snippets
Source
Ssh
Teams
Users
Webhooks
Workspaces
Other operations

Rate this page:

Branch restrictions

Repository owners and administrators can set branch management rules on a repository that control what can be pushed by whom. Through these rules, you can enforce a project or team workflow. For example, owners or administrators can:

  • Limit push powers
  • Prevent branch deletion
  • Prevent history re-writes (Git only)

List branch restrictions

GET /2.0/repositories/{workspace}/{repo_slug}/branch-restrictions

Returns a paginated list of all branch restrictions on the repository.

OAuth scopes required
repository:admin

Request

Path parameters
repo_slug Required

string

This can either be the repository slug or the UUID of the repository, surrounded by curly-braces, for example: {repository UUID}.

workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Query parameters
kind

string

Branch restrictions of this type

pattern

string

Branch restrictions applied to branches of this pattern

Example

1
2
3
4
curl --request GET \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/branch-restrictions' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

A paginated list of branch restrictions

Content typeValue
application/json

Paginated Branch Restrictions

Create a branch restriction rule

POST /2.0/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 and restrict_merges.

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.

OAuth scopes required
repository:admin

Request

Path parameters
repo_slug Required

string

This can either be the repository slug or the UUID of the repository, surrounded by curly-braces, for example: {repository UUID}.

workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Body parameters
Content typeValue
application/json

allOf [object, Branch Restriction]

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
curl --request POST \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/branch-restrictions' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "<string>",
  "links": {
    "self": {
      "href": "<string>",
      "name": "<string>"
    }
  },
  "id": 34,
  "kind": "require_tasks_to_be_completed",
  "branch_match_kind": "branching_model",
  "branch_type": "feature",
  "pattern": "<string>",
  "users": [
    {
      "type": "<string>"
    }
  ],
  "groups": [
    {
      "type": "<string>"
    }
  ],
  "value": 39
}'

Responses

A paginated list of branch restrictions

Content typeValue
application/json

allOf [object, Branch Restriction]

Get a branch restriction rule

GET /2.0/repositories/{workspace}/{repo_slug}/branch-restrictions/{id}

Returns a specific branch restriction rule.

OAuth scopes required
repository:admin

Request

Path parameters
id Required

string

The restriction rule's id

repo_slug Required

string

This can either be the repository slug or the UUID of the repository, surrounded by curly-braces, for example: {repository UUID}.

workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Example

1
2
3
4
curl --request GET \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/branch-restrictions/{id}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

The branch restriction rule

Content typeValue
application/json

allOf [object, Branch Restriction]

Update a branch restriction rule

PUT /2.0/repositories/{workspace}/{repo_slug}/branch-restrictions/{id}

Updates an existing branch restriction rule.

Fields not present in the request body are ignored.

See POST for details.

OAuth scopes required
repository:admin

Request

Path parameters
id Required

string

The restriction rule's id

repo_slug Required

string

This can either be the repository slug or the UUID of the repository, surrounded by curly-braces, for example: {repository UUID}.

workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Body parameters
Content typeValue
application/json

allOf [object, Branch Restriction]

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
curl --request PUT \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/branch-restrictions/{id}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "<string>",
  "links": {
    "self": {
      "href": "<string>",
      "name": "<string>"
    }
  },
  "id": 34,
  "kind": "require_tasks_to_be_completed",
  "branch_match_kind": "branching_model",
  "branch_type": "feature",
  "pattern": "<string>",
  "users": [
    {
      "type": "<string>"
    }
  ],
  "groups": [
    {
      "type": "<string>"
    }
  ],
  "value": 39
}'

Responses

The updated branch restriction rule

Content typeValue
application/json

allOf [object, Branch Restriction]

Delete a branch restriction rule

DELETE /2.0/repositories/{workspace}/{repo_slug}/branch-restrictions/{id}

Deletes an existing branch restriction rule.

OAuth scopes required
repository:admin

Request

Path parameters
id Required

string

The restriction rule's id

repo_slug Required

string

This can either be the repository slug or the UUID of the repository, surrounded by curly-braces, for example: {repository UUID}.

workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Example

1
2
3
curl --request DELETE \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/branch-restrictions/{id}' \
  --header 'Authorization: Bearer <access_token>'

Responses

Rate this page: