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

Update 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.

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.

RetriesRetries up to 2×, 500ms backoff, 30s timeout.

3 parameters · 11 body fields

ownerstringrequired

The account owner of the repository. The name is not case sensitive.

repostringrequired

The name of the repository without the `.git` extension. The name is not case sensitive.

branchstringrequired

The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use [the GraphQL API](https://docs.github.com/graphql).

required_status_checksobjectrequired

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

enforce_adminsbooleanrequired

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_reviewsobjectrequired

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

restrictionsobjectrequired

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.

required_linear_historybooleanoptional

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/github/administering-a-repository/requiring-a-linear-commit-history)" in the GitHub Help documentation.

allow_force_pushesbooleanoptional

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/github/administering-a-repository/enabling-force-pushes-to-a-protected-branch)" in the GitHub Help documentation."

allow_deletionsbooleanoptional

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/github/administering-a-repository/enabling-force-pushes-to-a-protected-branch)" in the GitHub Help documentation.

block_creationsbooleanoptional

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_resolutionbooleanoptional

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_branchbooleanoptional

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_syncingbooleanoptional

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

4 status codes

200Response

urlstringrequired

required_status_checksobjectoptional

Status Check Policy

required_pull_request_reviewsobjectoptional

required_signaturesobjectoptional

enforce_adminsobjectoptional

required_linear_historyobjectoptional

allow_force_pushesobjectoptional

allow_deletionsobjectoptional

restrictionsobjectoptional

Branch Restriction Policy

required_conversation_resolutionobjectoptional

block_creationsobjectoptional

lock_branchobjectoptional

Whether to set the branch as read-only. If this is true, users will not be able to push to the branch.

allow_fork_syncingobjectoptional

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.

403Forbidden

messagestringoptional

documentation_urlstringoptional

urlstringoptional

statusstringoptional

404Resource not found

messagestringoptional

documentation_urlstringoptional

urlstringoptional

statusstringoptional

422Validation failed, or the endpoint has been spammed.

messagestringrequired

documentation_urlstringrequired

errorsarray<string>optional

Error handling

A 403 is returned: Forbidden. A 404 is returned: Resource not found. A 422 is returned: Validation failed, or the endpoint has been spammed.

import { Client } from "acme-sdk";

const client = new Client({
  baseUrl: "https://api.acme.com",
  auth: { bearer: process.env.API_TOKEN },
  retry: {
    maxAttempts: 3,
    retryOn: [
      408,
      425,
      429,
      500,
      502,
      503,
      504,
    ],
    backoffMs: 500,
    maxBackoffMs: 8000,
  },
  timeoutMs: 30000,
});

const result = await client.protection.update({
  owner: "octocat",
  repo: "hello-world",
  branch: "main",
  requiredStatusChecks: {},
  enforceAdmins: true,
});

{
  "url": "https://api.github.com/repos/octocat/hello-world/branches/main/protection",
  "required_status_checks": {
    "url": "https://api.github.com/repos/octocat/hello-world/branches/main/protection/required_status_checks",
    "strict": true,
    "contexts": [
      "continuous-integration/travis-ci"
    ],
    "contexts_url": "https://api.github.com/repos/octocat/hello-world/branches/main/protection/required_status_checks/contexts",
    "checks": [
      {
        "context": "continuous-integration/travis-ci",
        "app_id": null
      }
    ]
  },
  "restrictions": {
    "url": "https://api.github.com/repos/octocat/hello-world/branches/main/protection/restrictions",
    "users_url": "https://api.github.com/repos/octocat/hello-world/branches/main/protection/restrictions/users",
    "teams_url": "https://api.github.com/repos/octocat/hello-world/branches/main/protection/restrictions/teams",
    "apps_url": "https://api.github.com/repos/octocat/hello-world/branches/main/protection/restrictions/apps",
    "users": [],
    "teams": [],
    "apps": []
  },
  "required_pull_request_reviews": {
    "url": "https://api.github.com/repos/octocat/hello-world/branches/main/protection/required_pull_request_reviews",
    "dismiss_stale_reviews": true,
    "require_code_owner_reviews": true,
    "required_approving_review_count": 2,
    "require_last_push_approval": true,
    "dismissal_restrictions": {
      "url": "https://api.github.com/repos/octocat/hello-world/branches/main/protection/dismissal_restrictions",
      "users_url": "https://api.github.com/repos/octocat/hello-world/branches/main/protection/dismissal_restrictions/users",
      "teams_url": "https://api.github.com/repos/octocat/hello-world/branches/main/protection/dismissal_restrictions/teams",
      "users": [],
      "teams": [],
      "apps": []
    }
  },
  "required_signatures": {
    "url": "https://api.github.com/repos/octocat/hello-world/branches/main/protection/required_signatures",
    "enabled": false
  },
  "enforce_admins": {
    "url": "https://api.github.com/repos/octocat/hello-world/branches/main/protection/enforce_admins",
    "enabled": true
  },
  "required_linear_history": {
    "enabled": true
  },
  "allow_force_pushes": {
    "enabled": true
  },
  "allow_deletions": {
    "enabled": true
  },
  "block_creations": {
    "enabled": true
  },
  "required_conversation_resolution": {
    "enabled": true
  },
  "lock_branch": {
    "enabled": true
  },
  "allow_fork_syncing": {
    "enabled": true
  }
}

Request

Response

Errors