Help Center/ CodeArts Repo/ API Reference/ APIs/ V4/ ProtectedRefs/ Protected Branch
Updated on 2026-04-28 GMT+08:00
View PDF

Protected Branch

Function

This API is used to update a protected branch.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

URI

PUT https://{hostURL}/v4/repositories/{repository_id}/protected-branch

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

repository_id

Yes

Integer

Definition

You can query the project list to obtain the repository ID by calling the API used to query user's all repositories.

Constraints

N/A.

Value range:

1~2147483647
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

branch_name

Yes

String

Definition:

Protected branch name or wildcard expression.

Constraints:

N/A.

Value range:

N/A.

Default value:

N/A.

Default value:

N/A

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Definition

User token. Obtain a token by calling the IAM API for obtaining a user token. The value of X-Subject-Token in the response header is the user token.

Constraints

Mandatory.

Range

1–100,000 characters.

Default Value

N/A.
Table 4 Request body parameters

Parameter

Mandatory

Type

Description

[items]

Yes

Array of ProtectedBranchProtectedActionBodyDto objects

Protected branch permission list.
Table 5 ProtectedBranchProtectedActionBodyDto

Parameter

Mandatory

Type

Description

enable

No

Boolean

Definition:

Whether to enable.

Constraints:

N/A.

Value range:

  • true: Yes.

  • false: No.

Default value:

N/A.

Default value:

true

user_ids

No

Array of integers

Definition:

User ID list.

Constraints:

N/A.

Value range:

Integer

Default value:

N/A.

Value range:

1~2147483647

user_team_ids

No

Array of integers

Definition:

Member group ID list.

Constraints:

N/A.

Value range:

N/A.

Default value:

N/A.

Value range:

1~2147483647

related_role_ids

No

Array of strings

Definition:

Associated role ID list.

Constraints:

N/A.

Value range:

N/A.

Default value:

N/A.

action

No

String

Definition:

Event name.

Constraints:

Mandatory.

Value range:

  • push: Push.

  • merge: Merge.

Default value:

N/A.

Enumeration values:

  • push

  • merge

addition_switchers

No

Array of ProtectedActionSwitcher objects

Definition:

Additional switch

Constraints:

N/A

Value range:

N/A

Default value:

N/A
Table 6 ProtectedActionSwitcher

Parameter

Mandatory

Type

Description

name

No

String

Definition:

Switch name

Constraints:

N/A

Value range:

  • allowed_force_push: force push is allowed (disabled by default).

Default value:

N/A

Enumeration values:

  • allowed_force_push

enable

No

Boolean

Definition:

Enabled or not

Constraints:

N/A

Value range:

  • true: enabled

  • false: disabled

Default value:

N/A

Response Parameters

Status code: 200

Table 7 Response body parameters

Parameter

Type

Description

id

Integer

Definition:

ID of the protected branch.

Value range:

1–2147483647

Value range:

1~2147483647

name

String

Definition:

Branch name or wildcard.

Value range:

N/A.

actions

Array of RepositoryProtectedActionDto objects

Definition:

Event list.

Value range:

N/A.
Table 8 RepositoryProtectedActionDto

Parameter

Type

Description

action

String

Definition:

Event name.

Value range:

N/A.

enable

Boolean

Definition:

Whether to enable.

Value range:

  • true: Yes.

  • false: No.

users

Array of RepositoryUserDto objects

Definition:

Whitelisted user list.

Value range:

N/A.

user_teams

Array of UserTeamBasicDto objects

Definition:

Whitelisted user group list.

Value range:

N/A.

roles

Array of BasicRoleDto objects

Definition:

Whitelisted role list.

Value range:

N/A.
Table 9 RepositoryUserDto

Parameter

Type

Description

id

Integer

Definition

User ID.

Value range:

1~2147483647

name

String

Definition

Username.

username

String

Definition

Username.

state

String

Definition:

User status

Value range:

  • active: activated

  • blocked: disabled

Enumeration values:

  • active

  • blocked

avatar_url

String

Definition:

Profile picture URL.

Value range:

N/A.

nick_name

String

Definition:

User alias.

Value range:

N/A.

tenant_name

String

Definition:

Tenant name.

Value range:

N/A.
Table 10 UserTeamBasicDto

Parameter

Type

Description

id

Integer

Definition:

User group ID.

Value range:

1–2147483647

name

String

Definition:

User group name.

Value range:

N/A.
Table 11 BasicRoleDto

Parameter

Type

Description

id

Integer

Definition:

Role ID.

Value range:

1–2147483647

name

String

Definition:

Role name.

Value range:

N/A.

related_role_id

String

Definition:

Associated role ID.

Value range:

N/A.

chinese_name

String

Definition:

Role name in Chinese.

Value range:

N/A.

Example Requests

This API is used to update a protected branch.

PUT /v4/repositories/123/protected-branch?branch_name=tt*

[ {
  "action" : "push",
  "enable" : true,
  "user_ids" : [ 9090 ],
  "user_team_ids" : [ 247, 521 ],
  "related_role_ids" : [ "Administrator", "24f72d0b611746c3a43da596ea5065f5" ]
}, {
  "action" : "merge",
  "enable" : true,
  "user_ids" : [ 9124 ],
  "user_team_ids" : [ 247 ],
  "related_role_ids" : [ "Administrator", "31bcd56943f0491fbc2f410d163f70cc", "24f72d0b611746c3a43da596ea5065f5" ]
} ]

Example Responses

Status code: 200

Protected branch.

{
  "id" : 2112012344,
  "name" : "t*",
  "actions" : [ {
    "action" : "push",
    "enable" : true,
    "users" : [ {
      "id" : 9493,
      "name" : "user",
      "username" : "84280e40b7974b9eaff329f8e43a5080",
      "state" : "active",
      "avatar_url" : "",
      "nick_name" : "user",
      "tenant_name" : "tenantName"
    } ],
    "user_teams" : [ {
      "id" : 247,
      "name" : "team-1"
    } ],
    "roles" : [ {
      "id" : 23836589,
      "name" : "Committer",
      "related_role_id" : "8425999e92974f2980b76b08ad423aa1",
      "chinese_name" : "Committer"
    }, {
      "id" : 23836590,
      "name" : "Developer",
      "related_role_id" : "f2464b129b064a6a988734a73c3f366b",
      "chinese_name" : "Developer"
    }, {
      "id" : 23836594,
      "name" : "Project manager",
      "related_role_id" : "6115a3ddd9044e288c558d1ae827a732",
      "chinese_name" : "Project manager"
    }, {
      "id" : 23836597,
      "name" : "Test manager",
      "related_role_id" : "24f72d0b611746c3a43da596ea5065f5",
      "chinese_name" : "Test manager"
    } ]
  }, {
    "action" : "merge",
    "enable" : true,
    "users" : [ {
      "id" : 9493,
      "name" : "user",
      "username" : "84280e40b7974b9eaff329f8e43a5080",
      "state" : "active",
      "avatar_url" : "",
      "nick_name" : "user",
      "tenant_name" : "tenantName"
    } ],
    "user_teams" : [ {
      "id" : 247,
      "name" : "team-1"
    } ],
    "roles" : [ {
      "id" : 23836589,
      "name" : "Committer",
      "related_role_id" : "8425999e92974f2980b76b08ad423aa1",
      "chinese_name" : "Committer"
    }, {
      "id" : 23836590,
      "name" : "Developer",
      "related_role_id" : "f2464b129b064a6a988734a73c3f366b",
      "chinese_name" : "Developer"
    }, {
      "id" : 23836595,
      "name" : "Administrator",
      "related_role_id" : "7a96af96176e4f728f571b8af8551dec",
      "chinese_name" : "Project administrator"
    }, {
      "id" : 23836597,
      "name" : "Test manager",
      "related_role_id" : "24f72d0b611746c3a43da596ea5065f5",
      "chinese_name" : "Test manager"
    } ]
  } ]
}

Status Codes

Status Code

Description

200

Protected branch.

Error Codes

See Error Codes.

Parent topic: ProtectedRefs