Skip to content
Try Gitea Cloud ☁️ for 30 days → Accelerate your Development & Deploys!
GiteaGitea Documentation
This is the documentation of 1.25.5, 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