REST API endpoints for protected branches - GitHub Enterprise Server 3.21 Docs

Get branch protection

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 in the GitHub Help documentation.

Fine-grained access tokens for "Get branch protection"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Administration" repository permissions (read)

Parameters for "Get branch protection"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository without the `.git` extension. The name is not case sensitive.
`branch` string Required The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API.

HTTP response status codes for "Get branch protection"

Status code	Description
`200`	OK
`404`	Resource not found

Code samples for "Get branch protection"

Request example

get/repos/{owner}/{repo}/branches/{branch}/protection

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/branches/BRANCH/protection

Response

Status: 200

{
  "url": "https://HOSTNAME/repos/octocat/Hello-World/branches/master/protection",
  "required_status_checks": {
    "url": "https://HOSTNAME/repos/octocat/Hello-World/branches/master/protection/required_status_checks",
    "contexts": [
      "continuous-integration/travis-ci"
    ],
    "contexts_url": "https://HOSTNAME/repos/octocat/Hello-World/branches/master/protection/required_status_checks/contexts",
    "enforcement_level": "non_admins"
  },
  "enforce_admins": {
    "url": "https://HOSTNAME/repos/octocat/Hello-World/branches/master/protection/enforce_admins",
    "enabled": true
  },
  "required_pull_request_reviews": {
    "url": "https://HOSTNAME/repos/octocat/Hello-World/branches/master/protection/required_pull_request_reviews",
    "dismissal_restrictions": {
      "url": "https://HOSTNAME/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions",
      "users_url": "https://HOSTNAME/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions/users",
      "teams_url": "https://HOSTNAME/repos/octocat/Hello-World/branches/master/protection/dismissal_restrictions/teams",
      "users": [
        {
          "login": "octocat",
          "id": 1,
          "node_id": "MDQ6VXNlcjE=",
          "avatar_url": "https://github.com/images/error/octocat_happy.gif",
          "gravatar_id": "",
          "url": "https://HOSTNAME/users/octocat",
          "html_url": "https://github.com/octocat",
          "followers_url": "https://HOSTNAME/users/octocat/followers",
          "following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
          "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
          "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
          "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
          "organizations_url": "https://HOSTNAME/users/octocat/orgs",
          "repos_url": "https://HOSTNAME/users/octocat/repos",
          "events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
          "received_events_url": "https://HOSTNAME/users/octocat/received_events",
          "type": "User",
          "site_admin": false
        }
      ],
      "teams": [
        {
          "id": 1,
          "node_id": "MDQ6VGVhbTE=",
          "url": "https://HOSTNAME/teams/1",
          "html_url": "https://github.com/orgs/github/teams/justice-league",
          "name": "Justice League",
          "slug": "justice-league",
          "description": "A great team.",
          "privacy": "closed",
          "notification_setting": "notifications_enabled",
          "permission": "admin",
          "members_url": "https://HOSTNAME/teams/1/members{/member}",
          "repositories_url": "https://HOSTNAME/teams/1/repos",
          "parent": null
        }
      ],
      "apps": [
        {
          "id": 1,
          "slug": "octoapp",
          "node_id": "MDExOkludGVncmF0aW9uMQ==",
          "owner": {
            "login": "github",
            "id": 1,
            "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
            "url": "https://HOSTNAME/orgs/github",
            "repos_url": "https://HOSTNAME/orgs/github/repos",
            "events_url": "https://HOSTNAME/orgs/github/events",
            "hooks_url": "https://HOSTNAME/orgs/github/hooks",
            "issues_url": "https://HOSTNAME/orgs/github/issues",
            "members_url": "https://HOSTNAME/orgs/github/members{/member}",
            "public_members_url": "https://HOSTNAME/orgs/github/public_members{/member}",
            "avatar_url": "https://github.com/images/error/octocat_happy.gif",
            "description": "A great organization"
          },
          "name": "Octocat App",
          "description": "",
          "external_url": "https://example.com",
          "html_url": "https://github.com/apps/octoapp",
          "created_at": "2017-07-08T16:18:44-04:00",
          "updated_at": "2017-07-08T16:18:44-04:00",
          "permissions": {
            "metadata": "read",
            "contents": "read",
            "issues": "write",
            "single_file": "write"
          },
          "events": [
            "push",
            "pull_request"
          ]
        }
      ]
    },
    "dismiss_stale_reviews": true,
    "require_code_owner_reviews": true,
    "required_approving_review_count": 2,
    "require_last_push_approval": true
  },
  "restrictions": {
    "url": "https://HOSTNAME/repos/octocat/Hello-World/branches/master/protection/restrictions",
    "users_url": "https://HOSTNAME/repos/octocat/Hello-World/branches/master/protection/restrictions/users",
    "teams_url": "https://HOSTNAME/repos/octocat/Hello-World/branches/master/protection/restrictions/teams",
    "apps_url": "https://HOSTNAME/repos/octocat/Hello-World/branches/master/protection/restrictions/apps",
    "users": [
      {
        "login": "octocat",
        "id": 1,
        "node_id": "MDQ6VXNlcjE=",
        "avatar_url": "https://github.com/images/error/octocat_happy.gif",
        "gravatar_id": "",
        "url": "https://HOSTNAME/users/octocat",
        "html_url": "https://github.com/octocat",
        "followers_url": "https://HOSTNAME/users/octocat/followers",
        "following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
        "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
        "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
        "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
        "organizations_url": "https://HOSTNAME/users/octocat/orgs",
        "repos_url": "https://HOSTNAME/users/octocat/repos",
        "events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
        "received_events_url": "https://HOSTNAME/users/octocat/received_events",
        "type": "User",
        "site_admin": false
      }
    ],
    "teams": [
      {
        "id": 1,
        "node_id": "MDQ6VGVhbTE=",
        "url": "https://HOSTNAME/teams/1",
        "html_url": "https://github.com/orgs/github/teams/justice-league",
        "name": "Justice League",
        "slug": "justice-league",
        "description": "A great team.",
        "privacy": "closed",
        "notification_setting": "notifications_enabled",
        "permission": "admin",
        "members_url": "https://HOSTNAME/teams/1/members{/member}",
        "repositories_url": "https://HOSTNAME/teams/1/repos",
        "parent": null
      }
    ],
    "apps": [
      {
        "id": 1,
        "slug": "octoapp",
        "node_id": "MDExOkludGVncmF0aW9uMQ==",
        "owner": {
          "login": "github",
          "id": 1,
          "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
          "url": "https://HOSTNAME/orgs/github",
          "repos_url": "https://HOSTNAME/orgs/github/repos",
          "events_url": "https://HOSTNAME/orgs/github/events",
          "hooks_url": "https://HOSTNAME/orgs/github/hooks",
          "issues_url": "https://HOSTNAME/orgs/github/issues",
          "members_url": "https://HOSTNAME/orgs/github/members{/member}",
          "public_members_url": "https://HOSTNAME/orgs/github/public_members{/member}",
          "avatar_url": "https://github.com/images/error/octocat_happy.gif",
          "description": "A great organization"
        },
        "name": "Octocat App",
        "description": "",
        "external_url": "https://example.com",
        "html_url": "https://github.com/apps/octoapp",
        "created_at": "2017-07-08T16:18:44-04:00",
        "updated_at": "2017-07-08T16:18:44-04:00",
        "permissions": {
          "metadata": "read",
          "contents": "read",
          "issues": "write",
          "single_file": "write"
        },
        "events": [
          "push",
          "pull_request"
        ]
      }
    ]
  },
  "required_linear_history": {
    "enabled": true
  },
  "allow_force_pushes": {
    "enabled": true
  },
  "allow_deletions": {
    "enabled": true
  },
  "required_conversation_resolution": {
    "enabled": true
  },
  "lock_branch": {
    "enabled": true
  },
  "allow_fork_syncing": {
    "enabled": true
  }
}

Update branch protection

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.

Fine-grained access tokens for "Update branch protection"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Administration" repository permissions (write)

Parameters for "Update branch protection"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository without the `.git` extension. The name is not case sensitive.
`branch` string Required The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API.

Name, Type, Description

required_status_checks object or null Required

Require status checks to pass before merging. Set to null to disable.

Properties of required_status_checks

Name, Type, Description

strict boolean Required

Require branches to be up to date before merging.

contexts array of strings Required

Closing down notice: 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.

checks array of objects

The list of status checks to require in order to merge into this branch.

Properties of checks

Name, Type, Description
`context` string Required The name of the required check
`app_id` integer 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.

enforce_admins boolean or null Required

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 object or null Required

Require at least one approving review on a pull request, before merging. Set to null to disable.

Properties of required_pull_request_reviews

Name, Type, Description

dismissal_restrictions object

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 of dismissal_restrictions

Name, Type, Description
`users` array of strings The list of user `login`s with dismissal access
`teams` array of strings The list of team `slug`s with dismissal access
`apps` array of strings The list of app `slug`s with dismissal access

dismiss_stale_reviews boolean

Set to true if you want to automatically dismiss approving reviews when someone pushes a new commit.

require_code_owner_reviews boolean