---
title: "Rename a branch"
method: POST
path: "/repos/{owner}/{repo}/branches/{branch}/rename"
tags: ["repos"]
---

# Rename a branch

`POST /repos/{owner}/{repo}/branches/{branch}/rename`

Renames a branch in a repository.

> [!NOTE]
> Although the API responds immediately, the branch rename process might take some extra time to complete in the background. You won't be able to push to the old branch name while the rename process is in progress. For more information, see "[Renaming a branch](https://docs.github.com/enterprise-cloud@latest/github/administering-a-repository/renaming-a-branch)".

The authenticated user must have push access to the branch. If the branch is the default branch, the authenticated user must also have admin or owner permissions.

In order to rename the default branch, fine-grained access tokens also need the `administration:write` repository permission.

## Path parameters

- `owner` string, required
- `repo` string, required
- `branch` string, required

## Request body

- object
  - `new_name` string, required — The new name of the branch.

## Response `201`

Response

- BranchWithProtection — Branch With Protection
  - `name` string, required
  - `commit` Commit, required — Commit
    - `url` string, uri, required
    - `sha` string, required
    - `node_id` string, required
    - `html_url` string, uri, required
    - `comments_url` string, uri, required
    - `commit` object, required
      - `url` string, uri, required
      - `author` NullableGitUser, nullable, required — Metaproperties for Git author/committer information.
        - `name` string
        - `email` string
        - `date` string, date-time
      - `committer` NullableGitUser, nullable, required — Metaproperties for Git author/committer information.
        - `name` string
        - `email` string
        - `date` string, date-time
      - `message` string, required
      - `comment_count` integer, required
      - `tree` object, required
        - `sha` string, required
        - `url` string, uri, required
      - `verification` Verification
        - `verified` boolean, required
        - `reason` string, required
        - `payload` string, nullable, required
        - `signature` string, nullable, required
        - `verified_at` string, nullable, required
    - `author` union, required
      - SimpleUser — A GitHub user.
        - `name` string, nullable
        - `email` string, nullable
        - `login` string, required
        - `id` integer, required
        - `node_id` string, required
        - `avatar_url` string, uri, required
        - `gravatar_id` string, nullable, required
        - `url` string, uri, required
        - `html_url` string, uri, required
        - `followers_url` string, uri, required
        - `following_url` string, required
        - `gists_url` string, required
        - `starred_url` string, required
        - `subscriptions_url` string, uri, required
        - `organizations_url` string, uri, required
        - `repos_url` string, uri, required
        - `events_url` string, required
        - `received_events_url` string, uri, required
        - `type` string, required
        - `site_admin` boolean, required
        - `starred_at` string
        - `user_view_type` string
      - EmptyObject — An object without any properties.
    - `committer` union, required
      - SimpleUser — A GitHub user.
        - `name` string, nullable
        - `email` string, nullable
        - `login` string, required
        - `id` integer, required
        - `node_id` string, required
        - `avatar_url` string, uri, required
        - `gravatar_id` string, nullable, required
        - `url` string, uri, required
        - `html_url` string, uri, required
        - `followers_url` string, uri, required
        - `following_url` string, required
        - `gists_url` string, required
        - `starred_url` string, required
        - `subscriptions_url` string, uri, required
        - `organizations_url` string, uri, required
        - `repos_url` string, uri, required
        - `events_url` string, required
        - `received_events_url` string, uri, required
        - `type` string, required
        - `site_admin` boolean, required
        - `starred_at` string
        - `user_view_type` string
      - EmptyObject — An object without any properties.
    - `parents` object[], required
      - `sha` string, required
      - `url` string, uri, required
      - `html_url` string, uri
    - `stats` object
      - `additions` integer
      - `deletions` integer
      - `total` integer
    - `files` DiffEntry[]
      - `sha` string, nullable, required
      - `filename` string, required
      - `status` 'added' | 'removed' | 'modified' | 'renamed' | 'copied' | 'changed' | 'unchanged', required
      - `additions` integer, required
      - `deletions` integer, required
      - `changes` integer, required
      - `blob_url` string, uri, required
      - `raw_url` string, uri, required
      - `contents_url` string, uri, required
      - `patch` string
      - `previous_filename` string
  - `_links` object, required
    - `html` string, required
    - `self` string, uri, required
  - `protected` boolean, required
  - `protection` BranchProtection, required — Branch Protection
    - `url` string
    - `enabled` boolean
    - `required_status_checks` ProtectedBranchRequiredStatusCheck — Protected Branch Required Status Check
      - `url` string
      - `enforcement_level` string
      - `contexts` string[], required
      - `checks` object[], required
        - `context` string, required
        - `app_id` integer, nullable, required
      - `contexts_url` string
      - `strict` boolean
    - `enforce_admins` ProtectedBranchAdminEnforced — Protected Branch Admin Enforced
      - `url` string, uri, required
      - `enabled` boolean, required
    - `required_pull_request_reviews` ProtectedBranchPullRequestReview — Protected Branch Pull Request Review
      - `url` string, uri
      - `dismissal_restrictions` object
        - `users` SimpleUser[] — The list of users with review dismissal access.
          - `name` string, nullable
          - `email` string, nullable
          - `login` string, required
          - `id` integer, required
          - `node_id` string, required
          - `avatar_url` string, uri, required
          - `gravatar_id` string, nullable, required
          - `url` string, uri, required
          - `html_url` string, uri, required
          - `followers_url` string, uri, required
          - `following_url` string, required
          - `gists_url` string, required
          - `starred_url` string, required
          - `subscriptions_url` string, uri, required
          - `organizations_url` string, uri, required
          - `repos_url` string, uri, required
          - `events_url` string, required
          - `received_events_url` string, uri, required
          - `type` string, required
          - `site_admin` boolean, required
          - `starred_at` string
          - `user_view_type` string
        - `teams` Team[] — The list of teams with review dismissal access.
          - `id` integer, required
          - `node_id` string, required
          - `name` string, required
          - `slug` string, required
          - `description` string, nullable, required
          - `privacy` string
          - `notification_setting` string
          - `permission` string, required
          - `permissions` object
            - `pull` boolean, required
            - `triage` boolean, required
            - `push` boolean, required
            - `maintain` boolean, required
            - `admin` boolean, required
          - `url` string, uri, required
          - `html_url` string, uri, required
          - `members_url` string, required
          - `repositories_url` string, uri, required
          - `type` 'enterprise' | 'organization', required — The ownership type of the team
          - `access_source` 'direct' | 'organization' | 'enterprise' — How the team's access to the repository was granted. This property is only present when the team is returned in a repository context, such as `GET /repos/{owner}/{repo}/teams`.
          - `organization_id` integer — Unique identifier of the organization to which this team belongs
          - `enterprise_id` integer — Unique identifier of the enterprise to which this team belongs
          - `parent` NullableTeamSimple, nullable, required — Groups of organization members that gives permissions on specified repositories.
            - `id` integer, required — Unique identifier of the team
            - `node_id` string, required
            - `url` string, uri, required — URL for the team
            - `members_url` string, required
            - `name` string, required — Name of the team
            - `description` string, nullable, required — Description of the team
            - `permission` string, required — Permission that the team will have for its repositories
            - `privacy` string — The level of privacy this team should have
            - `notification_setting` string — The notification setting the team has set
            - `html_url` string, uri, required
            - `repositories_url` string, uri, required
            - `slug` string, required
            - `ldap_dn` string — Distinguished Name (DN) that team maps to within LDAP environment
            - `type` 'enterprise' | 'organization', required — The ownership type of the team
            - `organization_id` integer — Unique identifier of the organization to which this team belongs
            - `enterprise_id` integer — Unique identifier of the enterprise to which this team belongs
        - `apps` Integration[] — The list of apps with review dismissal access.
          - `id` integer, required — Unique identifier of the GitHub app
          - `slug` string — The slug name of the GitHub app
          - `node_id` string, required
          - `client_id` string
          - `owner` union, required
            - SimpleUser — A GitHub user.
              - …
            - Enterprise — An enterprise on GitHub.
              - …
          - `name` string, required — The name of the GitHub app
          - `description` string, nullable, required
          - `external_url` string, uri, required
          - `html_url` string, uri, required
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
          - `permissions` object, required — The set of permissions for the GitHub app
            - `issues` string
            - `checks` string
            - `metadata` string
            - `contents` string
            - `deployments` string
          - `events` string[], required — The list of events for the GitHub app. Note that the `installation_target`, `security_advisory`, and `meta` events are not included because they are global events and not specific to an installation.
          - `installations_count` integer — The number of installations associated with the GitHub app. Only returned when the integration is requesting details about itself.
        - `url` string
        - `users_url` string
        - `teams_url` string
      - `bypass_pull_request_allowances` object — Allow specific users, teams, or apps to bypass pull request requirements.
        - `users` SimpleUser[] — The list of users allowed to bypass pull request requirements.
          - `name` string, nullable
          - `email` string, nullable
          - `login` string, required
          - `id` integer, required
          - `node_id` string, required
          - `avatar_url` string, uri, required
          - `gravatar_id` string, nullable, required
          - `url` string, uri, required
          - `html_url` string, uri, required
          - `followers_url` string, uri, required
          - `following_url` string, required
          - `gists_url` string, required
          - `starred_url` string, required
          - `subscriptions_url` string, uri, required
          - `organizations_url` string, uri, required
          - `repos_url` string, uri, required
          - `events_url` string, required
          - `received_events_url` string, uri, required
          - `type` string, required
          - `site_admin` boolean, required
          - `starred_at` string
          - `user_view_type` string
        - `teams` Team[] — The list of teams allowed to bypass pull request requirements.
          - `id` integer, required
          - `node_id` string, required
          - `name` string, required
          - `slug` string, required
          - `description` string, nullable, required
          - `privacy` string
          - `notification_setting` string
          - `permission` string, required
          - `permissions` object
            - `pull` boolean, required
            - `triage` boolean, required
            - `push` boolean, required
            - `maintain` boolean, required
            - `admin` boolean, required
          - `url` string, uri, required
          - `html_url` string, uri, required
          - `members_url` string, required
          - `repositories_url` string, uri, required
          - `type` 'enterprise' | 'organization', required — The ownership type of the team
          - `access_source` 'direct' | 'organization' | 'enterprise' — How the team's access to the repository was granted. This property is only present when the team is returned in a repository context, such as `GET /repos/{owner}/{repo}/teams`.
          - `organization_id` integer — Unique identifier of the organization to which this team belongs
          - `enterprise_id` integer — Unique identifier of the enterprise to which this team belongs
          - `parent` NullableTeamSimple, nullable, required — Groups of organization members that gives permissions on specified repositories.
            - `id` integer, required — Unique identifier of the team
            - `node_id` string, required
            - `url` string, uri, required — URL for the team
            - `members_url` string, required
            - `name` string, required — Name of the team
            - `description` string, nullable, required — Description of the team
            - `permission` string, required — Permission that the team will have for its repositories
            - `privacy` string — The level of privacy this team should have
            - `notification_setting` string — The notification setting the team has set
            - `html_url` string, uri, required
            - `repositories_url` string, uri, required
            - `slug` string, required
            - `ldap_dn` string — Distinguished Name (DN) that team maps to within LDAP environment
            - `type` 'enterprise' | 'organization', required — The ownership type of the team
            - `organization_id` integer — Unique identifier of the organization to which this team belongs
            - `enterprise_id` integer — Unique identifier of the enterprise to which this team belongs
        - `apps` Integration[] — The list of apps allowed to bypass pull request requirements.
          - `id` integer, required — Unique identifier of the GitHub app
          - `slug` string — The slug name of the GitHub app
          - `node_id` string, required
          - `client_id` string
          - `owner` union, required
            - SimpleUser — A GitHub user.
              - …
            - Enterprise — An enterprise on GitHub.
              - …
          - `name` string, required — The name of the GitHub app
          - `description` string, nullable, required
          - `external_url` string, uri, required
          - `html_url` string, uri, required
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
          - `permissions` object, required — The set of permissions for the GitHub app
            - `issues` string
            - `checks` string
            - `metadata` string
            - `contents` string
            - `deployments` string
          - `events` string[], required — The list of events for the GitHub app. Note that the `installation_target`, `security_advisory`, and `meta` events are not included because they are global events and not specific to an installation.
          - `installations_count` integer — The number of installations associated with the GitHub app. Only returned when the integration is requesting details about itself.
      - `dismiss_stale_reviews` boolean, required
      - `require_code_owner_reviews` boolean, required
      - `required_approving_review_count` integer
      - `require_last_push_approval` boolean — Whether the most recent push must be approved by someone other than the person who pushed it.
    - `restrictions` BranchRestrictionPolicy — Branch Restriction Policy
      - `url` string, uri, required
      - `users_url` string, uri, required
      - `teams_url` string, uri, required
      - `apps_url` string, uri, required
      - `users` object[], required
        - `login` string
        - `id` integer
        - `node_id` string
        - `avatar_url` string
        - `gravatar_id` string
        - `url` string
        - `html_url` string
        - `followers_url` string
        - `following_url` string
        - `gists_url` string
        - `starred_url` string
        - `subscriptions_url` string
        - `organizations_url` string
        - `repos_url` string
        - `events_url` string
        - `received_events_url` string
        - `type` string
        - `site_admin` boolean
        - `user_view_type` string
      - `teams` Team[], required
        - `id` integer, required
        - `node_id` string, required
        - `name` string, required
        - `slug` string, required
        - `description` string, nullable, required
        - `privacy` string
        - `notification_setting` string
        - `permission` string, required
        - `permissions` object
          - `pull` boolean, required
          - `triage` boolean, required
          - `push` boolean, required
          - `maintain` boolean, required
          - `admin` boolean, required
        - `url` string, uri, required
        - `html_url` string, uri, required
        - `members_url` string, required
        - `repositories_url` string, uri, required
        - `type` 'enterprise' | 'organization', required — The ownership type of the team
        - `access_source` 'direct' | 'organization' | 'enterprise' — How the team's access to the repository was granted. This property is only present when the team is returned in a repository context, such as `GET /repos/{owner}/{repo}/teams`.
        - `organization_id` integer — Unique identifier of the organization to which this team belongs
        - `enterprise_id` integer — Unique identifier of the enterprise to which this team belongs
        - `parent` NullableTeamSimple, nullable, required — Groups of organization members that gives permissions on specified repositories.
          - `id` integer, required — Unique identifier of the team
          - `node_id` string, required
          - `url` string, uri, required — URL for the team
          - `members_url` string, required
          - `name` string, required — Name of the team
          - `description` string, nullable, required — Description of the team
          - `permission` string, required — Permission that the team will have for its repositories
          - `privacy` string — The level of privacy this team should have
          - `notification_setting` string — The notification setting the team has set
          - `html_url` string, uri, required
          - `repositories_url` string, uri, required
          - `slug` string, required
          - `ldap_dn` string — Distinguished Name (DN) that team maps to within LDAP environment
          - `type` 'enterprise' | 'organization', required — The ownership type of the team
          - `organization_id` integer — Unique identifier of the organization to which this team belongs
          - `enterprise_id` integer — Unique identifier of the enterprise to which this team belongs
      - `apps` object[], required
        - `id` integer
        - `slug` string
        - `node_id` string
        - `owner` object
          - `login` string
          - `id` integer
          - `node_id` string
          - `url` string
          - `repos_url` string
          - `events_url` string
          - `hooks_url` string
          - `issues_url` string
          - `members_url` string
          - `public_members_url` string
          - `avatar_url` string
          - `description` string
          - `gravatar_id` string
          - `html_url` string
          - `followers_url` string
          - `following_url` string
          - `gists_url` string
          - `starred_url` string
          - `subscriptions_url` string
          - `organizations_url` string
          - `received_events_url` string
          - `type` string
          - `site_admin` boolean
          - `user_view_type` string
        - `name` string
        - `client_id` string
        - `description` string
        - `external_url` string
        - `html_url` string
        - `created_at` string
        - `updated_at` string
        - `permissions` object
          - `metadata` string
          - `contents` string
          - `issues` string
          - `single_file` string
        - `events` string[]
    - `required_linear_history` object
      - `enabled` boolean
    - `allow_force_pushes` object
      - `enabled` boolean
    - `allow_deletions` object
      - `enabled` boolean
    - `block_creations` object
      - `enabled` boolean
    - `required_conversation_resolution` object
      - `enabled` boolean
    - `name` string
    - `protection_url` string
    - `required_signatures` object
      - `url` string, uri, required
      - `enabled` boolean, required
    - `lock_branch` object — Whether to set the branch as read-only. If this is true, users will not be able to push to the branch.
      - `enabled` boolean
    - `allow_fork_syncing` object — Whether users can pull changes from upstream when the branch is locked. Set to `true` to allow fork syncing. Set to `false` to prevent fork syncing.
      - `enabled` boolean
  - `protection_url` string, uri, required
  - `pattern` string
  - `required_approving_review_count` integer

## Other responses

- `403` — Forbidden
- `404` — Resource not found
- `422` — Validation failed, or the endpoint has been spammed.

---

[API](https://skmtc.net/github/apis/github-v3-rest-api-3.md) · [All operations](https://skmtc.net/github/apis/github-v3-rest-api-3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/github/github-v3-rest-api-3/versions/dc0584ac4e13/schema)