Skip to content
Try Gitea Cloud ☁️ for 30 days → Accelerate your Development & Deploys!
GiteaGitea Documentation
This is the documentation of 1.26.4, which is no longer the latest release. See the latest release.

Create a branch protections for a repository

POST
/repos/{owner}/{repo}/branch_protections
curl --request POST \
  --url https://gitea.com/api/v1/repos/example/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", "dismiss_stale_approvals": true, "enable_approvals_whitelist": 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" ], "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" }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
owner
required
string

Owner of the repo

repo
required
string

Name of the repo

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
dismiss_stale_approvals
boolean
enable_approvals_whitelist
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>
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",
  "dismiss_stale_approvals": true,
  "enable_approvals_whitelist": 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"
  ],
  "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 ”

201

Section titled “201”

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
created_at
string format: date-time
dismiss_stale_approvals
boolean
enable_approvals_whitelist
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>
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",
  "created_at": "2026-04-15T12:00:00Z",
  "dismiss_stale_approvals": true,
  "enable_approvals_whitelist": 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"
  ],
  "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"
}

403

Section titled “403”

APIForbiddenError is a forbidden error response

Media typeapplication/json

Headers

Section titled “Headers”
message
string
url
string

404

Section titled “404”

APINotFound is a not found empty response

Media typeapplication/json

422

Section titled “422”

APIValidationError is error format response related to input validation

Media typeapplication/json

Headers

Section titled “Headers”
message
string
url
string

423

Section titled “423”

APIRepoArchivedError is an error that is raised when an archived repo should be modified

Media typeapplication/json

Headers

Section titled “Headers”
message
string
url
string