The GitHub Branches API lets you list, create, and manage branches in a repository, including configuring branch protection rules that enforce required status checks, pull request reviews, signed commits, and restrictions on who can push. It also supports managing branch protection settings for admins and teams.
openapi: 3.1.0
info:
version: 1.1.4
title: github-repos-api
description: |-
Use the REST API to create, manage and control the workflow of public and
private GitHub repositories.
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://docs.github.com/articles/github-terms-of-service
contact:
name: Support
url: https://support.github.com/contact
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: api.github.com
protocol:
description: Self-hosted Enterprise Server protocol
default: https
externalDocs:
description: GitHub Enterprise Developer Docs
url: https://docs.github.com/[email protected]/rest/
tags:
- name: Access
- name: Add
- name: Administrative
- name: All
- name: Applications
- name: Branches
- name: Checks
- name: Commits
- name: Contexts
- name: Create
- name: Delete
- name: Get
- name: Protected
- name: Protections
- name: Pull
- name: Remove
- name: Rename
- name: Requests
- name: Restrictions
- name: Reviews
- name: Sets
- name: Signatures
- name: Status
- name: Teams
- name: Update
- name: Users
paths:
/repos/{owner}/{repo}/branches/{branch}:
get:
summary: GitHub Get Branch
description: |-
The Get Branch endpoint retrieves detailed information about a specific branch in a GitHub repository. By making a GET request to /repos/{owner}/{repo}/branches/{branch}, you can access comprehensive data about the branch including its name, commit SHA, protection status, and associated metadata. This operation requires you to provide the repository owner's username, the repository name, and the specific branch name as path parameters. The response includes the branch's latest commit information, protection rules if enabled, and links to related resources. This endpoint is particularly useful for verifying branch existence, checking protection settings, or retrieving the current commit reference before performing operations like merges or deployments.
tags:
- Branches
- Get
operationId: getBranch
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/branches/branches#get-a-branch
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/branch-with-protection'
examples:
default:
$ref: '#/components/examples/branch-get'
'301':
$ref: '#/components/responses/moved_permanently'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: branches
subcategory: branches
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/branches/{branch}/protection:
get:
summary: GitHub Get Branch Protection
description: |-
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub's products](https://docs.github.com/[email protected]/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
tags:
- Branches
- Get
- Protections
operationId: getBranchProtection
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/branches/branch-protection#get-branch-protection
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/branch-protection'
examples:
default:
$ref: '#/components/examples/branch-protection'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Update Branch Protection
description: |-
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub's products](https://docs.github.com/[email protected]/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Protecting a branch requires admin or owner permissions to the repository.
**Note**: Passing new arrays of `users` and `teams` replaces their previous values.
**Note**: The list of users, apps, and teams in total is limited to 100 items.
tags:
- Branches
- Protections
- Update
operationId: updateBranchProtection
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/branches/branch-protection#update-branch-protection
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
required_status_checks:
type: object
description: |-
Require status checks to pass before merging. Set to `null` to disable.
properties:
strict:
type: boolean
description: Require branches to be up to date before merging.
contexts:
type: array
deprecated: true
description: |
**Deprecated**: The list of status checks to require in order to merge into this branch. If any of these checks have recently been set by a particular GitHub App, they will be required to come from that app in future for the branch to merge. Use `checks` instead of `contexts` for more fine-grained control.
items:
type: string
checks:
type: array
description: |-
The list of status checks to require in order to merge into this branch.
items:
type: object
required:
- context
properties:
context:
type: string
description: The name of the required check
app_id:
type: integer
description: |-
The ID of the GitHub App that must provide this check. Omit this field to automatically select the GitHub App that has recently provided this check, or any app if it was not set by a GitHub App. Pass -1 to explicitly allow any app to set the status.
required:
- strict
- contexts
enforce_admins:
type: boolean
description: |-
Enforce all configured restrictions for administrators. Set to `true` to enforce required status checks for repository administrators. Set to `null` to disable.
required_pull_request_reviews:
type: object
description: |-
Require at least one approving review on a pull request, before merging. Set to `null` to disable.
properties:
dismissal_restrictions:
type: object
description: |-
Specify which users, teams, and apps can dismiss pull request reviews. Pass an empty `dismissal_restrictions` object to disable. User and team `dismissal_restrictions` are only available for organization-owned repositories. Omit this parameter for personal repositories.
properties:
users:
type: array
description: The list of user `login`s with dismissal access
items:
type: string
teams:
type: array
description: The list of team `slug`s with dismissal access
items:
type: string
apps:
type: array
description: The list of app `slug`s with dismissal access
items:
type: string
dismiss_stale_reviews:
type: boolean
description: |-
Set to `true` if you want to automatically dismiss approving reviews when someone pushes a new commit.
require_code_owner_reviews:
type: boolean
description: |-
Blocks merging pull requests until [code owners](https://docs.github.com/[email protected]/articles/about-code-owners/) review them.
required_approving_review_count:
type: integer
description: |-
Specify the number of reviewers required to approve pull requests. Use a number between 1 and 6 or 0 to not require reviewers.
require_last_push_approval:
type: boolean
description: |-
Whether the most recent push must be approved by someone other than the person who pushed it. Default: `false`.
default: false
bypass_pull_request_allowances:
type: object
description: |-
Allow specific users, teams, or apps to bypass pull request requirements.
properties:
users:
type: array
description: |-
The list of user `login`s allowed to bypass pull request requirements.
items:
type: string
teams:
type: array
description: |-
The list of team `slug`s allowed to bypass pull request requirements.
items:
type: string
apps:
type: array
description: |-
The list of app `slug`s allowed to bypass pull request requirements.
items:
type: string
restrictions:
type: object
description: |-
Restrict who can push to the protected branch. User, app, and team `restrictions` are only available for organization-owned repositories. Set to `null` to disable.
properties:
users:
type: array
description: The list of user `login`s with push access
items:
type: string
teams:
type: array
description: The list of team `slug`s with push access
items:
type: string
apps:
type: array
description: The list of app `slug`s with push access
items:
type: string
required:
- users
- teams
required_linear_history:
type: boolean
description: |-
Enforces a linear commit Git history, which prevents anyone from pushing merge commits to a branch. Set to `true` to enforce a linear commit history. Set to `false` to disable a linear commit Git history. Your repository must allow squash merging or rebase merging before you can enable a linear commit history. Default: `false`. For more information, see "[Requiring a linear commit history](https://docs.github.com/[email protected]/github/administering-a-repository/requiring-a-linear-commit-history)" in the GitHub Help documentation.
allow_force_pushes:
type: boolean
description: |-
Permits force pushes to the protected branch by anyone with write access to the repository. Set to `true` to allow force pushes. Set to `false` or `null` to block force pushes. Default: `false`. For more information, see "[Enabling force pushes to a protected branch](https://docs.github.com/[email protected]/github/administering-a-repository/enabling-force-pushes-to-a-protected-branch)" in the GitHub Help documentation."
allow_deletions:
type: boolean
description: |-
Allows deletion of the protected branch by anyone with write access to the repository. Set to `false` to prevent deletion of the protected branch. Default: `false`. For more information, see "[Enabling force pushes to a protected branch](https://docs.github.com/[email protected]/github/administering-a-repository/enabling-force-pushes-to-a-protected-branch)" in the GitHub Help documentation.
block_creations:
type: boolean
description: |-
If set to `true`, the `restrictions` branch protection settings which limits who can push will also block pushes which create new branches, unless the push is initiated by a user, team, or app which has the ability to push. Set to `true` to restrict new branch creation. Default: `false`.
required_conversation_resolution:
type: boolean
description: |-
Requires all conversations on code to be resolved before a pull request can be merged into a branch that matches this rule. Set to `false` to disable. Default: `false`.
lock_branch:
type: boolean
description: |-
Whether to set the branch as read-only. If this is true, users will not be able to push to the branch. Default: `false`.
default: false
allow_fork_syncing:
type: boolean
description: |-
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. Default: `false`.
default: false
required:
- required_status_checks
- enforce_admins
- required_pull_request_reviews
- restrictions
examples:
default:
value:
required_status_checks:
strict: true
contexts:
- continuous-integration/travis-ci
enforce_admins: true
required_pull_request_reviews:
dismissal_restrictions:
users:
- octocat
teams:
- justice-league
dismiss_stale_reviews: true
require_code_owner_reviews: true
required_approving_review_count: 2
require_last_push_approval: true
bypass_pull_request_allowances:
users:
- octocat
teams:
- justice-league
restrictions:
users:
- octocat
teams:
- justice-league
apps:
- super-ci
required_linear_history: true
allow_force_pushes: true
allow_deletions: true
block_creations: true
required_conversation_resolution: true
lock_branch: true
allow_fork_syncing: true
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/protected-branch'
examples:
default:
$ref: '#/components/examples/branch-protection-update'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed_simple'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete Branch Protection
description: |-
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub's products](https://docs.github.com/[email protected]/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
tags:
- Branches
- Delete
- Protections
operationId: deleteBranchProtection
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/branches/branch-protection#delete-branch-protection
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'204':
description: Response
'403':
$ref: '#/components/responses/forbidden'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins:
get:
summary: GitHub Get Admin Branch Protection
description: |-
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub's products](https://docs.github.com/[email protected]/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
tags:
- Administrative
- Branches
- Get
- Protections
operationId: getAdminBranchProtection
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/branches/branch-protection#get-admin-branch-protection
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/protected-branch-admin-enforced'
examples:
default:
$ref: '#/components/examples/protected-branch-admin-enforced-2'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Set Admin Branch Protection
description: |-
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub's products](https://docs.github.com/[email protected]/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Adding admin enforcement requires admin or owner permissions to the repository and branch protection to be enabled.
tags:
- Administrative
- Branches
- Protections
- Sets
operationId: setAdminBranchProtection
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/branches/branch-protection#set-admin-branch-protection
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/protected-branch-admin-enforced'
examples:
default:
$ref: '#/components/examples/protected-branch-admin-enforced-2'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete Admin Branch Protection
description: |-
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub's products](https://docs.github.com/[email protected]/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Removing admin enforcement requires admin or owner permissions to the repository and branch protection to be enabled.
tags:
- Administrative
- Branches
- Delete
- Protections
operationId: deleteAdminBranchProtection
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/branches/branch-protection#delete-admin-branch-protection
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'204':
description: Response
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews:
get:
summary: GitHub Get Pull Request Review Protection
description: |-
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub's products](https://docs.github.com/[email protected]/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
tags:
- Get
- Protections
- Pull
- Requests
- Reviews
operationId: getPullRequestReviewProtection
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/branches/branch-protection#get-pull-request-review-protection
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/protected-branch-pull-request-review'
examples:
default:
$ref: '#/components/examples/protected-branch-pull-request-review'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update Pull Request Review Protection
description: |-
Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub's products](https://docs.github.com/[email protected]/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.
Updating pull request review enforcement requires admin or owner permissions to the repository and branch protection to be enabled.
**Note**: Passing new arrays of `users` and `teams` replaces their previous values.
tags:
- Protections
- Pull
- Requests
- Reviews
- Update
operationId: updatePullRequestReviewProtection
externalDocs:
description: API method documentation
url: |-
https://docs.github.com/[email protected]/rest/branches/branch-protection#update-pull-request-review-protection
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
dismissal_restrictions:
type: object
description: |-
Specify which users, teams, and apps can dismiss pull request reviews. Pass an empty `dismissal_restrictions` object to disable. User and team `dismissal_restrictions` are only available for organization-owned repositories. Omit this parameter for personal repositories.
properties:
users:
type: array
description: The list of user `login`s with dismissal access
items:
type: string
teams:
type: array
description: The list of team `slug`s with dismissal access
items:
type: string
apps:
type: array
description: The list of app `slug`s with dismissal access
items:
type:
# --- truncated at 32 KB (182 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-repo-branches-api-openapi.yml