Skip to main content
The Gitea API provides comprehensive endpoints for managing repository branches, including creating, listing, updating, and deleting branches, as well as managing branch protection rules.

​
List Branches

List all branches in a repository. 
GET /repos/{owner}/{repo}/branches

​
Path Parameters

​
owner
string
required
Owner of the repository
​
repo
string
required
Name of the repository

​
Query Parameters

​
page
integer
default:"1"
Page number of results (1-based)
​
limit
integer
Page size of results

​
Response

Returns an array of branch objects.
​
name
string
Branch name
​
commit
object
Latest commit information
​
id
string
Commit SHA
​
message
string
Commit message
​
timestamp
string
Commit timestamp (ISO 8601)
​
protected
boolean
Whether the branch is protected
​
required_approvals
integer
Number of required approvals for PRs to this branch
​
enable_status_check
boolean
Whether status checks are enabled
​
status_check_contexts
array
List of required status check contexts
​
user_can_push
boolean
Whether the current user can push to this branch
​
user_can_merge
boolean
Whether the current user can merge to this branch
​
effective_branch_protection_name
string
Name of the effective branch protection rule
curl -X GET "https://gitea.example.com/api/v1/repos/username/repo-name/branches" \
  -H "Authorization: token YOUR_TOKEN"

​
Get Branch

Retrieve a specific branch from a repository, including its effective branch protection. 
GET /repos/{owner}/{repo}/branches/{branch}

​
Path Parameters

​
owner
string
required
Owner of the repository
​
repo
string
required
Name of the repository
​
branch
string
required
Name of the branch to retrieve
curl -X GET "https://gitea.example.com/api/v1/repos/username/repo-name/branches/main" \
  -H "Authorization: token YOUR_TOKEN"

​
Create Branch

Create a new branch in a repository. 
POST /repos/{owner}/{repo}/branches

​
Path Parameters

​
owner
string
required
Owner of the repository
​
repo
string
required
Name of the repository

​
Request Body

​
new_branch_name
string
required
Name of the branch to create
​
old_ref_name
string
Name of the reference (branch/tag/commit SHA) to create the branch from. If not specified, uses the default branch.

​
Response

Returns the created branch object. 
curl -X POST "https://gitea.example.com/api/v1/repos/username/repo-name/branches" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "new_branch_name": "feature/new-feature",
    "old_ref_name": "main"
  }'
The repository must not be empty, and branch names must follow Git reference naming conventions.

​
Update Branch

Update a branch reference to point to a new commit. 
PUT /repos/{owner}/{repo}/branches/{branch}

​
Path Parameters

​
owner
string
required
Owner of the repository
​
repo
string
required
Name of the repository
​
branch
string
required
Name of the branch to update

​
Request Body

​
new_commit_id
string
required
New commit SHA to point the branch to
​
old_commit_id
string
Expected current commit SHA (for safety check)
​
force
boolean
default:"false"
Force update even if it’s not a fast-forward
curl -X PUT "https://gitea.example.com/api/v1/repos/username/repo-name/branches/feature-branch" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "new_commit_id": "def456abc789",
    "old_commit_id": "abc123def456"
  }'
Force updating a branch can cause data loss if other users have based work on the old commit. Use with caution.

​
Rename Branch

Rename an existing branch. 
PATCH /repos/{owner}/{repo}/branches/{branch}

​
Path Parameters

​
owner
string
required
Owner of the repository
​
repo
string
required
Name of the repository
​
branch
string
required
Current name of the branch

​
Request Body

​
name
string
required
New name for the branch
curl -X PATCH "https://gitea.example.com/api/v1/repos/username/repo-name/branches/old-name" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-name"
  }'
Renaming protected branches or the default branch requires admin or owner permissions.

​
Delete Branch

Delete a specific branch from a repository. 
DELETE /repos/{owner}/{repo}/branches/{branch}

​
Path Parameters

​
owner
string
required
Owner of the repository
​
repo
string
required
Name of the repository
​
branch
string
required
Name of the branch to delete
curl -X DELETE "https://gitea.example.com/api/v1/repos/username/repo-name/branches/feature-branch" \
  -H "Authorization: token YOUR_TOKEN"
  • You cannot delete the default branch
  • You cannot delete protected branches without proper permissions
  • Deleting a branch is permanent and cannot be undone

​
Branch Protection

​
List Branch Protections

List all branch protection rules for a repository. 
GET /repos/{owner}/{repo}/branch_protections

curl -X GET "https://gitea.example.com/api/v1/repos/username/repo-name/branch_protections" \
  -H "Authorization: token YOUR_TOKEN"

​
Get Branch Protection

Get a specific branch protection rule. 
GET /repos/{owner}/{repo}/branch_protections/{name}

​
Create Branch Protection

Create a new branch protection rule. 
POST /repos/{owner}/{repo}/branch_protections

​
Request Body

​
rule_name
string
required
Name of the branch protection rule (can be branch name or pattern like release/*)
​
priority
integer
default:"0"
Priority of this rule (higher priority rules are matched first)
​
enable_push
boolean
default:"false"
Allow push to this branch
​
enable_push_whitelist
boolean
default:"false"
Restrict push to whitelisted users/teams
​
push_whitelist_usernames
array
Usernames allowed to push
​
push_whitelist_teams
array
Team names allowed to push
​
enable_merge_whitelist
boolean
default:"false"
Restrict merge to whitelisted users/teams
​
merge_whitelist_usernames
array
Usernames allowed to merge
​
merge_whitelist_teams
array
Team names allowed to merge
​
enable_status_check
boolean
default:"false"
Require status checks to pass before merging
​
status_check_contexts
array
Required status check contexts that must pass
​
required_approvals
integer
default:"0"
Number of required approvals before merging
​
enable_approvals_whitelist
boolean
default:"false"
Only count approvals from whitelisted users/teams
​
block_on_rejected_reviews
boolean
default:"false"
Block merge if there are rejected reviews
​
dismiss_stale_approvals
boolean
default:"false"
Dismiss approvals when new commits are pushed
​
require_signed_commits
boolean
default:"false"
Require all commits to be signed
​
block_on_outdated_branch
boolean
default:"false"
Block merge if branch is not up to date with base
curl -X POST "https://gitea.example.com/api/v1/repos/username/repo-name/branch_protections" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rule_name": "main",
    "enable_push": false,
    "enable_merge_whitelist": true,
    "merge_whitelist_usernames": ["admin"],
    "required_approvals": 2,
    "enable_status_check": true,
    "status_check_contexts": ["ci/test"],
    "require_signed_commits": true
  }'

​
Update Branch Protection

Edit an existing branch protection rule. Only provided fields will be changed. 
PATCH /repos/{owner}/{repo}/branch_protections/{name}

curl -X PATCH "https://gitea.example.com/api/v1/repos/username/repo-name/branch_protections/main" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "required_approvals": 3,
    "status_check_contexts": ["ci/test", "ci/lint", "ci/security"]
  }'

​
Delete Branch Protection

Delete a branch protection rule. 
DELETE /repos/{owner}/{repo}/branch_protections/{name}

curl -X DELETE "https://gitea.example.com/api/v1/repos/username/repo-name/branch_protections/main" \
  -H "Authorization: token YOUR_TOKEN"

​
Merge Upstream

For forked repositories, merge changes from the upstream repository. 
POST /repos/{owner}/{repo}/merge-upstream

​
Request Body

​
branch
string
required
Branch to merge into (typically the default branch)
​
ff_only
boolean
default:"false"
Only perform fast-forward merge
curl -X POST "https://gitea.example.com/api/v1/repos/username/forked-repo/merge-upstream" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "main"
  }'
This endpoint only works for repositories that are forks. The merge type can be merge, fast-forward, or already-up-to-date.

Build docs developers (and LLMs) love

Get started for freeTalk to us