> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/go-gitea/gitea/llms.txt
> Use this file to discover all available pages before exploring further.

# Branch Management

> Manage repository branches via the Gitea API

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.

```bash theme={null}
GET /repos/{owner}/{repo}/branches
```

### Path Parameters

<ParamField path="owner" type="string" required>
  Owner of the repository
</ParamField>

<ParamField path="repo" type="string" required>
  Name of the repository
</ParamField>

### Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number of results (1-based)
</ParamField>

<ParamField query="limit" type="integer">
  Page size of results
</ParamField>

### Response

Returns an array of branch objects.

<ResponseField name="name" type="string">
  Branch name
</ResponseField>

<ResponseField name="commit" type="object">
  Latest commit information

  <ResponseField name="id" type="string">
    Commit SHA
  </ResponseField>

  <ResponseField name="message" type="string">
    Commit message
  </ResponseField>

  <ResponseField name="timestamp" type="string">
    Commit timestamp (ISO 8601)
  </ResponseField>
</ResponseField>

<ResponseField name="protected" type="boolean">
  Whether the branch is protected
</ResponseField>

<ResponseField name="required_approvals" type="integer">
  Number of required approvals for PRs to this branch
</ResponseField>

<ResponseField name="enable_status_check" type="boolean">
  Whether status checks are enabled
</ResponseField>

<ResponseField name="status_check_contexts" type="array">
  List of required status check contexts
</ResponseField>

<ResponseField name="user_can_push" type="boolean">
  Whether the current user can push to this branch
</ResponseField>

<ResponseField name="user_can_merge" type="boolean">
  Whether the current user can merge to this branch
</ResponseField>

<ResponseField name="effective_branch_protection_name" type="string">
  Name of the effective branch protection rule
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://gitea.example.com/api/v1/repos/username/repo-name/branches" \
    -H "Authorization: token YOUR_TOKEN"
  ```

  ```json Response theme={null}
  [
    {
      "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
    }
  ]
  ```
</CodeGroup>

## Get Branch

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

```bash theme={null}
GET /repos/{owner}/{repo}/branches/{branch}
```

### Path Parameters

<ParamField path="owner" type="string" required>
  Owner of the repository
</ParamField>

<ParamField path="repo" type="string" required>
  Name of the repository
</ParamField>

<ParamField path="branch" type="string" required>
  Name of the branch to retrieve
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://gitea.example.com/api/v1/repos/username/repo-name/branches/main" \
    -H "Authorization: token YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

## Create Branch

Create a new branch in a repository.

```bash theme={null}
POST /repos/{owner}/{repo}/branches
```

### Path Parameters

<ParamField path="owner" type="string" required>
  Owner of the repository
</ParamField>

<ParamField path="repo" type="string" required>
  Name of the repository
</ParamField>

### Request Body

<ParamField body="new_branch_name" type="string" required>
  Name of the branch to create
</ParamField>

<ParamField body="old_ref_name" type="string">
  Name of the reference (branch/tag/commit SHA) to create the branch from. If not specified, uses the default branch.
</ParamField>

### Response

Returns the created branch object.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```bash Create from Commit theme={null}
  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"
    }'
  ```

  ```json Response theme={null}
  {
    "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
  }
  ```
</CodeGroup>

<Note>
  The repository must not be empty, and branch names must follow Git reference naming conventions.
</Note>

## Update Branch

Update a branch reference to point to a new commit.

```bash theme={null}
PUT /repos/{owner}/{repo}/branches/{branch}
```

### Path Parameters

<ParamField path="owner" type="string" required>
  Owner of the repository
</ParamField>

<ParamField path="repo" type="string" required>
  Name of the repository
</ParamField>

<ParamField path="branch" type="string" required>
  Name of the branch to update
</ParamField>

### Request Body

<ParamField body="new_commit_id" type="string" required>
  New commit SHA to point the branch to
</ParamField>

<ParamField body="old_commit_id" type="string">
  Expected current commit SHA (for safety check)
</ParamField>

<ParamField body="force" type="boolean" default="false">
  Force update even if it's not a fast-forward
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```bash Force Update theme={null}
  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
    }'
  ```
</CodeGroup>

<Warning>
  Force updating a branch can cause data loss if other users have based work on the old commit. Use with caution.
</Warning>

## Rename Branch

Rename an existing branch.

```bash theme={null}
PATCH /repos/{owner}/{repo}/branches/{branch}
```

### Path Parameters

<ParamField path="owner" type="string" required>
  Owner of the repository
</ParamField>

<ParamField path="repo" type="string" required>
  Name of the repository
</ParamField>

<ParamField path="branch" type="string" required>
  Current name of the branch
</ParamField>

### Request Body

<ParamField body="name" type="string" required>
  New name for the branch
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

<Note>
  Renaming protected branches or the default branch requires admin or owner permissions.
</Note>

## Delete Branch

Delete a specific branch from a repository.

```bash theme={null}
DELETE /repos/{owner}/{repo}/branches/{branch}
```

### Path Parameters

<ParamField path="owner" type="string" required>
  Owner of the repository
</ParamField>

<ParamField path="repo" type="string" required>
  Name of the repository
</ParamField>

<ParamField path="branch" type="string" required>
  Name of the branch to delete
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://gitea.example.com/api/v1/repos/username/repo-name/branches/feature-branch" \
    -H "Authorization: token YOUR_TOKEN"
  ```
</CodeGroup>

<Warning>
  * You cannot delete the default branch
  * You cannot delete protected branches without proper permissions
  * Deleting a branch is permanent and cannot be undone
</Warning>

## Branch Protection

### List Branch Protections

List all branch protection rules for a repository.

```bash theme={null}
GET /repos/{owner}/{repo}/branch_protections
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://gitea.example.com/api/v1/repos/username/repo-name/branch_protections" \
    -H "Authorization: token YOUR_TOKEN"
  ```

  ```json Response theme={null}
  [
    {
      "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"
    }
  ]
  ```
</CodeGroup>

### Get Branch Protection

Get a specific branch protection rule.

```bash theme={null}
GET /repos/{owner}/{repo}/branch_protections/{name}
```

### Create Branch Protection

Create a new branch protection rule.

```bash theme={null}
POST /repos/{owner}/{repo}/branch_protections
```

### Request Body

<ParamField body="rule_name" type="string" required>
  Name of the branch protection rule (can be branch name or pattern like `release/*`)
</ParamField>

<ParamField body="priority" type="integer" default="0">
  Priority of this rule (higher priority rules are matched first)
</ParamField>

<ParamField body="enable_push" type="boolean" default="false">
  Allow push to this branch
</ParamField>

<ParamField body="enable_push_whitelist" type="boolean" default="false">
  Restrict push to whitelisted users/teams
</ParamField>

<ParamField body="push_whitelist_usernames" type="array">
  Usernames allowed to push
</ParamField>

<ParamField body="push_whitelist_teams" type="array">
  Team names allowed to push
</ParamField>

<ParamField body="enable_merge_whitelist" type="boolean" default="false">
  Restrict merge to whitelisted users/teams
</ParamField>

<ParamField body="merge_whitelist_usernames" type="array">
  Usernames allowed to merge
</ParamField>

<ParamField body="merge_whitelist_teams" type="array">
  Team names allowed to merge
</ParamField>

<ParamField body="enable_status_check" type="boolean" default="false">
  Require status checks to pass before merging
</ParamField>

<ParamField body="status_check_contexts" type="array">
  Required status check contexts that must pass
</ParamField>

<ParamField body="required_approvals" type="integer" default="0">
  Number of required approvals before merging
</ParamField>

<ParamField body="enable_approvals_whitelist" type="boolean" default="false">
  Only count approvals from whitelisted users/teams
</ParamField>

<ParamField body="block_on_rejected_reviews" type="boolean" default="false">
  Block merge if there are rejected reviews
</ParamField>

<ParamField body="dismiss_stale_approvals" type="boolean" default="false">
  Dismiss approvals when new commits are pushed
</ParamField>

<ParamField body="require_signed_commits" type="boolean" default="false">
  Require all commits to be signed
</ParamField>

<ParamField body="block_on_outdated_branch" type="boolean" default="false">
  Block merge if branch is not up to date with base
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```json Response theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

### Update Branch Protection

Edit an existing branch protection rule. Only provided fields will be changed.

```bash theme={null}
PATCH /repos/{owner}/{repo}/branch_protections/{name}
```

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```
</CodeGroup>

### Delete Branch Protection

Delete a branch protection rule.

```bash theme={null}
DELETE /repos/{owner}/{repo}/branch_protections/{name}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://gitea.example.com/api/v1/repos/username/repo-name/branch_protections/main" \
    -H "Authorization: token YOUR_TOKEN"
  ```
</CodeGroup>

## Merge Upstream

For forked repositories, merge changes from the upstream repository.

```bash theme={null}
POST /repos/{owner}/{repo}/merge-upstream
```

### Request Body

<ParamField body="branch" type="string" required>
  Branch to merge into (typically the default branch)
</ParamField>

<ParamField body="ff_only" type="boolean" default="false">
  Only perform fast-forward merge
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```json Response theme={null}
  {
    "merge_type": "merge"
  }
  ```
</CodeGroup>

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