Branch Management

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

string

required

Owner of the repository

string

required

Name of the repository

Query Parameters

integer

default:"1"

Page number of results (1-based)

integer

Page size of results

Response

Returns an array of branch objects.

string

Branch name

object

Latest commit information

string

Commit SHA

string

Commit message

string

Commit timestamp (ISO 8601)

boolean

Whether the branch is protected

integer

Number of required approvals for PRs to this branch

boolean

Whether status checks are enabled

array

List of required status check contexts

boolean

Whether the current user can push to this branch

boolean

Whether the current user can merge to this branch

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"

[
  {
    "name": "main",
    "commit": {
      "id": "abc123def456",
      "message": "Update README",
      "timestamp": "2024-03-10T12:00:00Z"
    },
    "protected": true,
    "required_approvals": 2,
    "enable_status_check": true,
    "status_check_contexts": ["ci/test", "ci/lint"],
    "user_can_push": false,
    "user_can_merge": true,
    "effective_branch_protection_name": "main-protection"
  },
  {
    "name": "develop",
    "commit": {
      "id": "def456abc789",
      "message": "Add feature",
      "timestamp": "2024-03-09T15:30:00Z"
    },
    "protected": false,
    "user_can_push": true,
    "user_can_merge": true
  }
]

Get Branch

Retrieve a specific branch from a repository, including its effective branch protection.

GET /repos/{owner}/{repo}/branches/{branch}

Path Parameters

string

required

Owner of the repository

string

required

Name of the repository

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"

{
  "name": "main",
  "commit": {
    "id": "abc123def456",
    "message": "Update README",
    "author": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "timestamp": "2024-03-10T12:00:00Z"
  },
  "protected": true,
  "required_approvals": 2,
  "enable_status_check": true,
  "status_check_contexts": ["ci/test"],
  "user_can_push": false,
  "user_can_merge": true,
  "effective_branch_protection_name": "main-protection"
}

Create Branch

Create a new branch in a repository.

POST /repos/{owner}/{repo}/branches

Path Parameters

string

required

Owner of the repository

string

required

Name of the repository

Request Body

string

required

Name of the branch to create

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"
  }'

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": "hotfix/urgent-fix",
    "old_ref_name": "abc123def456"
  }'

{
  "name": "feature/new-feature",
  "commit": {
    "id": "abc123def456",
    "message": "Update README",
    "timestamp": "2024-03-10T12:00:00Z"
  },
  "protected": false,
  "user_can_push": true,
  "user_can_merge": true
}

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

string

required

Owner of the repository

string

required

Name of the repository

string

required

Name of the branch to update

Request Body

string

required

New commit SHA to point the branch to

string

Expected current commit SHA (for safety check)

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"
  }'

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",
    "force": true
  }'

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

string

required

Owner of the repository

string

required

Name of the repository

string

required

Current name of the branch

Request Body

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

string

required

Owner of the repository

string

required

Name of the repository

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"

[
  {
    "rule_name": "main-protection",
    "priority": 1,
    "enable_push": false,
    "enable_merge_whitelist": true,
    "merge_whitelist_usernames": ["admin", "maintainer"],
    "required_approvals": 2,
    "enable_status_check": true,
    "status_check_contexts": ["ci/test", "ci/lint"],
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-03-10T12:00:00Z"
  }
]

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

string

required

Name of the branch protection rule (can be branch name or pattern like release/*)

integer

default:"0"

Priority of this rule (higher priority rules are matched first)

boolean

default:"false"

Allow push to this branch

boolean

default:"false"

Restrict push to whitelisted users/teams

array

Usernames allowed to push

array

Team names allowed to push

boolean

default:"false"

Restrict merge to whitelisted users/teams

array

Usernames allowed to merge

array

Team names allowed to merge

boolean

default:"false"

Require status checks to pass before merging

array

Required status check contexts that must pass

integer

default:"0"

Number of required approvals before merging

boolean

default:"false"

Only count approvals from whitelisted users/teams

boolean

default:"false"

Block merge if there are rejected reviews

boolean

default:"false"

Dismiss approvals when new commits are pushed

boolean

default:"false"

Require all commits to be signed

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
  }'

{
  "rule_name": "main",
  "priority": 0,
  "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,
  "created_at": "2024-03-10T12:00:00Z",
  "updated_at": "2024-03-10T12:00:00Z"
}

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

string

required

Branch to merge into (typically the default branch)

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"
  }'

{
  "merge_type": "merge"
}

This endpoint only works for repositories that are forks. The merge type can be merge, fast-forward, or already-up-to-date.

Overview

Repositories

Issues & Pull Requests

Organizations & Teams

Users

Actions & Packages

Branch Management

List Branches

Path Parameters

Query Parameters

Response

Get Branch

Path Parameters

Create Branch

Path Parameters

Request Body

Response

Update Branch

Path Parameters

Request Body

Rename Branch

Path Parameters

Request Body

Delete Branch

Path Parameters

Branch Protection

List Branch Protections

Get Branch Protection

Create Branch Protection

Request Body

Update Branch Protection

Delete Branch Protection

Merge Upstream

Request Body

​List Branches

​Path Parameters

​Query Parameters

​Response

​Get Branch

​Path Parameters

​Create Branch

​Path Parameters

​Request Body

​Response

​Update Branch

​Path Parameters

​Request Body

​Rename Branch

​Path Parameters

​Request Body

​Delete Branch

​Path Parameters

​Branch Protection

​List Branch Protections

​Get Branch Protection

​Create Branch Protection

​Request Body

​Update Branch Protection

​Delete Branch Protection

​Merge Upstream

​Request Body

List Branches

Path Parameters

Query Parameters

Response

Get Branch

Path Parameters

Create Branch

Path Parameters

Request Body

Response

Update Branch

Path Parameters

Request Body

Rename Branch

Path Parameters

Request Body

Delete Branch

Path Parameters

Branch Protection

List Branch Protections

Get Branch Protection

Create Branch Protection

Request Body

Update Branch Protection

Delete Branch Protection

Merge Upstream

Request Body