Skip to content
Try Gitea Cloud ☁️ for 30 days → Accelerate your Development & Deploys!
GiteaGitea Documentation

Create a branch

POST
/repos/{owner}/{repo}/branches
curl --request POST \
  --url https://gitea.com/api/v1/repos/example/example/branches \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '{ "new_branch_name": "example", "old_branch_name": "example", "old_ref_name": "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

CreateBranchRepoOption options when creating a branch in a repository

object
new_branch_name
required

Name of the branch to create

string
unique items
old_branch_name

Deprecated: true Name of the old branch to create from

string
unique items
old_ref_name

Name of the old branch/tag/commit to create from

string
unique items
Examplegenerated
{
  "new_branch_name": "example",
  "old_branch_name": "example",
  "old_ref_name": "example"
}

Responses

Section titled “Responses”

201

Section titled “201”

Branch

Media typeapplication/json

Branch represents a repository branch

object
commit

PayloadCommit represents a commit

object
added

List of files added in this commit

Array<string>
author

PayloadUser represents the author or committer of a commit

object
email
string format: email
name

Full name of the commit author

string
username

Username of the user

string
committer

PayloadUser represents the author or committer of a commit

object
email
string format: email
name

Full name of the commit author

string
username

Username of the user

string
id

Sha1 hash of the commit

string
message

The commit message

string
modified

List of files modified in this commit

Array<string>
removed

List of files removed in this commit

Array<string>
timestamp
string format: date-time
url

The URL to view this commit

string format: uri
verification

PayloadCommitVerification represents the GPG verification of a commit

object
payload

The signed payload content

string
reason

The reason for the verification status

string
signature

The GPG signature of the commit

string
signer

PayloadUser represents the author or committer of a commit

object
email
string format: email
name

Full name of the commit author

string
username

Username of the user

string
verified

Whether the commit signature is verified

boolean
effective_branch_protection_name

EffectiveBranchProtectionName is the name of the effective branch protection rule

string
enable_status_check

EnableStatusCheck indicates if status checks are enabled

boolean
name

Name is the branch name

string
protected

Protected indicates if the branch is protected

boolean
required_approvals

RequiredApprovals is the number of required approvals for pull requests

integer format: int64
status_check_contexts

StatusCheckContexts contains the list of required status check contexts

Array<string>
user_can_merge

UserCanMerge indicates if the current user can merge to this branch

boolean
user_can_push

UserCanPush indicates if the current user can push to this branch

boolean
Examplegenerated
{
  "commit": {
    "added": [
      "example"
    ],
    "author": {
      "email": "hello@example.com",
      "name": "example",
      "username": "example"
    },
    "committer": {
      "email": "hello@example.com",
      "name": "example",
      "username": "example"
    },
    "id": "example",
    "message": "example",
    "modified": [
      "example"
    ],
    "removed": [
      "example"
    ],
    "timestamp": "2026-04-15T12:00:00Z",
    "url": "https://example.com",
    "verification": {
      "payload": "example",
      "reason": "example",
      "signature": "example",
      "signer": {
        "email": "hello@example.com",
        "name": "example",
        "username": "example"
      },
      "verified": true
    }
  },
  "effective_branch_protection_name": "example",
  "enable_status_check": true,
  "name": "example",
  "protected": true,
  "required_approvals": 1,
  "status_check_contexts": [
    "example"
  ],
  "user_can_merge": true,
  "user_can_push": true
}

403

Section titled “403”

The branch is archived or a mirror.

404

Section titled “404”

The old branch does not exist.

409

Section titled “409”

The branch with the same name already exists.

423

Section titled “423”

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

Headers

Section titled “Headers”
message
string
url
string