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.

Authorizations

• oauth2
  repository:admin
• basic
• api_key

Parameters

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

Request Body ^required

The new rule

Media type application/json

object

type

required

string

links

object

self

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

id

The branch restriction status’ id.

integer

kind

required

The type of restriction that is being applied.

string

Allowed values: 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

branch_match_kind

required

Indicates how the restriction is matched against a branch. The default is glob.

string

Allowed values: branching_model glob

branch_type

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.

string

Allowed values: feature bugfix release hotfix development production

pattern

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.

string

value

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.

integer

users

Array

0

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

groups

Array

0

object

type

required

string

links

object

self

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

owner

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

workspace

object

type

required

string

links

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

members

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

owners

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

projects

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

repositories

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

snippets

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

self

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

uuid

The workspace’s immutable id.

string

name

The name of the workspace.

string

slug

The short label that identifies this workspace.

string

is_private

Indicates whether the workspace is publicly accessible, or whether it is private to the members and consequently only visible to members.

boolean

is_privacy_enforced

Indicates whether the workspace enforces private content, or whether it allows public content.

boolean

forking_mode

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

string

Allowed values: allow_forks internal_only

created_on

string format: date-time

updated_on

string format: date-time

name

string

slug

The “sluggified” version of the group’s name. This contains only ASCII characters and can therefore be slightly different than the name

string

full_slug

The concatenation of the workspace’s slug and the group’s slug, separated with a colon (e.g. acme:developers)

string

Responses

201

A paginated list of branch restrictions

Media type application/json

object

type

required

string

links

object

self

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

id

The branch restriction status’ id.

integer

kind

required

The type of restriction that is being applied.

string

Allowed values: 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

branch_match_kind

required

Indicates how the restriction is matched against a branch. The default is glob.

string

Allowed values: branching_model glob

branch_type

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.

string

Allowed values: feature bugfix release hotfix development production

pattern

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.

string

value

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.

integer

users

Array

0

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

groups

Array

0

object

type

required

string

links

object

self

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

owner

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

workspace

object

type

required

string

links

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

members

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

owners

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

projects

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

repositories

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

snippets

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

self

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

uuid

The workspace’s immutable id.

string

name

The name of the workspace.

string

slug

The short label that identifies this workspace.

string

is_private

Indicates whether the workspace is publicly accessible, or whether it is private to the members and consequently only visible to members.

boolean

is_privacy_enforced

Indicates whether the workspace enforces private content, or whether it allows public content.

boolean

forking_mode

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

string

Allowed values: allow_forks internal_only

created_on

string format: date-time

updated_on

string format: date-time

name

string

slug

The “sluggified” version of the group’s name. This contains only ASCII characters and can therefore be slightly different than the name

string

full_slug

The concatenation of the workspace’s slug and the group’s slug, separated with a colon (e.g. acme:developers)

string

Example

{
  "kind": "push",
  "branch_match_kind": "branching_model",
  "branch_type": "feature",
  "groups": [
    {
      "workspace": {
        "forking_mode": "allow_forks"
      }
    }
  ]
}

401

If the request was not authenticated

Media type application/json

Error

Base type for most resource objects. It defines the common type element that identifies an object’s type. It also identifies the element as Swagger’s discriminator.

object

type

required

string

error

object

message

required

string

detail

string

data

Optional structured data that is endpoint-specific.

object

key

additional properties

any

key

additional properties

any

Example ^generated

{
  "type": "example",
  "error": {
    "message": "example",
    "detail": "example",
    "data": {}
  }
}

403

If the authenticated user does not have admin access to the repository

Media type application/json

Error

Base type for most resource objects. It defines the common type element that identifies an object’s type. It also identifies the element as Swagger’s discriminator.

object

type

required

string

error

object

message

required

string

detail

string

data

Optional structured data that is endpoint-specific.

object

key

additional properties

any

key

additional properties

any

Example ^generated

{
  "type": "example",
  "error": {
    "message": "example",
    "detail": "example",
    "data": {}
  }
}

404

If the repository does not exist

Media type application/json

Error

Base type for most resource objects. It defines the common type element that identifies an object’s type. It also identifies the element as Swagger’s discriminator.

object

type

required

string

error

object

message

required

string

detail

string

data

Optional structured data that is endpoint-specific.

object

key

additional properties

any

key

additional properties

any

Example ^generated

{
  "type": "example",
  "error": {
    "message": "example",
    "detail": "example",
    "data": {}
  }
}