Create a branch protection rule for an organization
POST
/orgs/{org}/branch_protections
const url = 'https://gitea.example.com/api/v1/orgs/example/branch_protections';const options = { method: 'POST', headers: {Authorization: 'Basic <credentials>', 'Content-Type': 'application/json'}, body: '{"approvals_whitelist_teams":["example"],"approvals_whitelist_username":["example"],"block_admin_merge_override":true,"block_on_official_review_requests":true,"block_on_outdated_branch":true,"block_on_rejected_reviews":true,"branch_name":"example","bypass_allowlist_teams":["example"],"bypass_allowlist_usernames":["example"],"dismiss_stale_approvals":true,"enable_approvals_whitelist":true,"enable_bypass_allowlist":true,"enable_force_push":true,"enable_force_push_allowlist":true,"enable_merge_whitelist":true,"enable_push":true,"enable_push_whitelist":true,"enable_status_check":true,"force_push_allowlist_deploy_keys":true,"force_push_allowlist_teams":["example"],"force_push_allowlist_usernames":["example"],"ignore_stale_approvals":true,"merge_whitelist_teams":["example"],"merge_whitelist_usernames":["example"],"path_rules":[{"can_push":true,"enable_whitelist":true,"exclude_file_patterns":"example","file_patterns":"example","name":"example","push_whitelist_teams":["example"],"push_whitelist_usernames":["example"]}],"priority":1,"protected_file_patterns":"example","push_whitelist_deploy_keys":true,"push_whitelist_teams":["example"],"push_whitelist_usernames":["example"],"require_signed_commits":true,"required_approvals":1,"rule_name":"example","status_check_contexts":["example"],"unprotected_file_patterns":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://gitea.example.com/api/v1/orgs/example/branch_protections \ --header 'Authorization: Basic <credentials>' \ --header 'Content-Type: application/json' \ --data '{ "approvals_whitelist_teams": [ "example" ], "approvals_whitelist_username": [ "example" ], "block_admin_merge_override": true, "block_on_official_review_requests": true, "block_on_outdated_branch": true, "block_on_rejected_reviews": true, "branch_name": "example", "bypass_allowlist_teams": [ "example" ], "bypass_allowlist_usernames": [ "example" ], "dismiss_stale_approvals": true, "enable_approvals_whitelist": true, "enable_bypass_allowlist": true, "enable_force_push": true, "enable_force_push_allowlist": true, "enable_merge_whitelist": true, "enable_push": true, "enable_push_whitelist": true, "enable_status_check": true, "force_push_allowlist_deploy_keys": true, "force_push_allowlist_teams": [ "example" ], "force_push_allowlist_usernames": [ "example" ], "ignore_stale_approvals": true, "merge_whitelist_teams": [ "example" ], "merge_whitelist_usernames": [ "example" ], "path_rules": [ { "can_push": true, "enable_whitelist": true, "exclude_file_patterns": "example", "file_patterns": "example", "name": "example", "push_whitelist_teams": [ "example" ], "push_whitelist_usernames": [ "example" ] } ], "priority": 1, "protected_file_patterns": "example", "push_whitelist_deploy_keys": true, "push_whitelist_teams": [ "example" ], "push_whitelist_usernames": [ "example" ], "require_signed_commits": true, "required_approvals": 1, "rule_name": "example", "status_check_contexts": [ "example" ], "unprotected_file_patterns": "example" }'Gitea Enterprise only. This endpoint is not part of the community edition.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”org
required
string
Name of the organization
Request Body
Section titled “Request Body”Media typeapplication/json
CreateBranchProtectionOption options for creating a branch protection
object
approvals_whitelist_teams
Array<string>
approvals_whitelist_username
Array<string>
block_admin_merge_override
boolean
block_on_official_review_requests
boolean
block_on_outdated_branch
boolean
block_on_rejected_reviews
boolean
branch_name
Deprecated: true
string
bypass_allowlist_teams
Array<string>
bypass_allowlist_usernames
Array<string>
dismiss_stale_approvals
boolean
enable_approvals_whitelist
boolean
enable_bypass_allowlist
boolean
enable_force_push
boolean
enable_force_push_allowlist
boolean
enable_merge_whitelist
boolean
enable_push
boolean
enable_push_whitelist
boolean
enable_status_check
boolean
force_push_allowlist_deploy_keys
boolean
force_push_allowlist_teams
Array<string>
force_push_allowlist_usernames
Array<string>
ignore_stale_approvals
boolean
merge_whitelist_teams
Array<string>
merge_whitelist_usernames
Array<string>
path_rules
For Gitea EE: the ordered path-level write rules of this branch protection rule
Array<object>
PathRule represents a single path-level write rule of a branch protection rule
object
can_push
boolean
enable_whitelist
boolean
exclude_file_patterns
ExcludeFilePatterns excludes matched paths from the scope of this rule
string
file_patterns
FilePatterns is the scope of this rule (semicolon separated globs)
string
name
string
push_whitelist_teams
Array<string>
push_whitelist_usernames
Array<string>
priority
integer format: int64
protected_file_patterns
string
push_whitelist_deploy_keys
boolean
push_whitelist_teams
Array<string>
push_whitelist_usernames
Array<string>
require_signed_commits
boolean
required_approvals
integer format: int64
rule_name
string
status_check_contexts
Array<string>
unprotected_file_patterns
string
Examplegenerated
{ "approvals_whitelist_teams": [ "example" ], "approvals_whitelist_username": [ "example" ], "block_admin_merge_override": true, "block_on_official_review_requests": true, "block_on_outdated_branch": true, "block_on_rejected_reviews": true, "branch_name": "example", "bypass_allowlist_teams": [ "example" ], "bypass_allowlist_usernames": [ "example" ], "dismiss_stale_approvals": true, "enable_approvals_whitelist": true, "enable_bypass_allowlist": true, "enable_force_push": true, "enable_force_push_allowlist": true, "enable_merge_whitelist": true, "enable_push": true, "enable_push_whitelist": true, "enable_status_check": true, "force_push_allowlist_deploy_keys": true, "force_push_allowlist_teams": [ "example" ], "force_push_allowlist_usernames": [ "example" ], "ignore_stale_approvals": true, "merge_whitelist_teams": [ "example" ], "merge_whitelist_usernames": [ "example" ], "path_rules": [ { "can_push": true, "enable_whitelist": true, "exclude_file_patterns": "example", "file_patterns": "example", "name": "example", "push_whitelist_teams": [ "example" ], "push_whitelist_usernames": [ "example" ] } ], "priority": 1, "protected_file_patterns": "example", "push_whitelist_deploy_keys": true, "push_whitelist_teams": [ "example" ], "push_whitelist_usernames": [ "example" ], "require_signed_commits": true, "required_approvals": 1, "rule_name": "example", "status_check_contexts": [ "example" ], "unprotected_file_patterns": "example"}Responses
Section titled “Responses”BranchProtection
Media typeapplication/json
BranchProtection represents a branch protection for a repository
object
approvals_whitelist_teams
Array<string>
approvals_whitelist_username
Array<string>
block_admin_merge_override
boolean
block_on_official_review_requests
boolean
block_on_outdated_branch
boolean
block_on_rejected_reviews
boolean
branch_name
Deprecated: true
string
bypass_allowlist_teams
Array<string>
bypass_allowlist_usernames
Array<string>
created_at
string format: date-time
dismiss_stale_approvals
boolean
enable_approvals_whitelist
boolean
enable_bypass_allowlist
boolean
enable_force_push
boolean
enable_force_push_allowlist
boolean
enable_merge_whitelist
boolean
enable_push
boolean
enable_push_whitelist
boolean
enable_status_check
boolean
force_push_allowlist_deploy_keys
boolean
force_push_allowlist_teams
Array<string>
force_push_allowlist_usernames
Array<string>
ignore_stale_approvals
boolean
merge_whitelist_teams
Array<string>
merge_whitelist_usernames
Array<string>
path_rules
For Gitea EE: the ordered path-level write rules of this branch protection rule
Array<object>
PathRule represents a single path-level write rule of a branch protection rule
object
can_push
boolean
enable_whitelist
boolean
exclude_file_patterns
ExcludeFilePatterns excludes matched paths from the scope of this rule
string
file_patterns
FilePatterns is the scope of this rule (semicolon separated globs)
string
name
string
push_whitelist_teams
Array<string>
push_whitelist_usernames
Array<string>
priority
Priority is the priority of this branch protection rule
integer format: int64
protected_file_patterns
string
push_whitelist_deploy_keys
boolean
push_whitelist_teams
Array<string>
push_whitelist_usernames
Array<string>
require_signed_commits
boolean
required_approvals
integer format: int64
rule_name
RuleName is the name of the branch protection rule
string
status_check_contexts
Array<string>
unprotected_file_patterns
string
updated_at
string format: date-time
Examplegenerated
{ "approvals_whitelist_teams": [ "example" ], "approvals_whitelist_username": [ "example" ], "block_admin_merge_override": true, "block_on_official_review_requests": true, "block_on_outdated_branch": true, "block_on_rejected_reviews": true, "branch_name": "example", "bypass_allowlist_teams": [ "example" ], "bypass_allowlist_usernames": [ "example" ], "created_at": "2026-04-15T12:00:00Z", "dismiss_stale_approvals": true, "enable_approvals_whitelist": true, "enable_bypass_allowlist": true, "enable_force_push": true, "enable_force_push_allowlist": true, "enable_merge_whitelist": true, "enable_push": true, "enable_push_whitelist": true, "enable_status_check": true, "force_push_allowlist_deploy_keys": true, "force_push_allowlist_teams": [ "example" ], "force_push_allowlist_usernames": [ "example" ], "ignore_stale_approvals": true, "merge_whitelist_teams": [ "example" ], "merge_whitelist_usernames": [ "example" ], "path_rules": [ { "can_push": true, "enable_whitelist": true, "exclude_file_patterns": "example", "file_patterns": "example", "name": "example", "push_whitelist_teams": [ "example" ], "push_whitelist_usernames": [ "example" ] } ], "priority": 1, "protected_file_patterns": "example", "push_whitelist_deploy_keys": true, "push_whitelist_teams": [ "example" ], "push_whitelist_usernames": [ "example" ], "require_signed_commits": true, "required_approvals": 1, "rule_name": "example", "status_check_contexts": [ "example" ], "unprotected_file_patterns": "example", "updated_at": "2026-04-15T12:00:00Z"}APIForbiddenError is a forbidden error response
Headers
Section titled “Headers”message
string
url
string
APINotFound is a not found empty response
APIValidationError is error format response related to input validation
Headers
Section titled “Headers”message
string
url
string