# Update branch protection

From **GitHub v3 REST API**.

`PUT /repos/{owner}/{repo}/branches/{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](https://docs.github.com/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.

## Parameters

### `owner`

- Location: path
- Required: true
- Type: `string`

### `repo`

- Location: path
- Required: true
- Type: `string`

### `branch`

- Location: path
- Required: true
- Type: `string`

The name of the branch.

## Request body

- Required: true
### `application/json`

- Type: `object`

```json
{
  "allow_deletions": true,
  "allow_force_pushes": true,
  "enforce_admins": true,
  "required_conversation_resolution": true,
  "required_linear_history": true,
  "required_pull_request_reviews": {
    "bypass_pull_request_allowances": {
      "teams": [
        "justice-league"
      ],
      "users": [
        "octocat"
      ]
    },
    "dismiss_stale_reviews": true,
    "dismissal_restrictions": {
      "teams": [
        "justice-league"
      ],
      "users": [
        "octocat"
      ]
    },
    "require_code_owner_reviews": true,
    "required_approving_review_count": 2
  },
  "required_status_checks": {
    "contexts": [
      "continuous-integration/travis-ci"
    ],
    "strict": true
  },
  "restrictions": {
    "apps": [
      "super-ci"
    ],
    "teams": [
      "justice-league"
    ],
    "users": [
      "octocat"
    ]
  }
}
```

```json
{"properties":{"allow_deletions":{"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/en/github/administering-a-repository/enabling-force-pushes-to-a-protected-branch)\" in the GitHub Help documentation.","type":"boolean"},"allow_force_pushes":{"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/en/github/administering-a-repository/enabling-force-pushes-to-a-protected-branch)\" in the GitHub Help documentation.\"","nullable":true,"type":"boolean"},"contexts":{"description":"The list of status checks to require in order to merge into this branch.","items":{"type":"string"},"type":"array"},"enforce_admins":{"description":"Enforce all configured restrictions for administrators. Set to `true` to enforce required status checks for repository administrators. Set to `null` to disable.","nullable":true,"type":"boolean"},"required_conversation_resolution":{"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`.","type":"boolean"},"required_linear_history":{"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/github/administering-a-repository/requiring-a-linear-commit-history)\" in the GitHub Help documentation.","type":"boolean"},"required_pull_request_reviews":{"description":"Require at least one approving review on a pull request, before merging. Set to `null` to disable.","nullable":true,"properties":{"dismiss_stale_reviews":{"description":"Set to `true` if you want to automatically dismiss approving reviews when someone pushes a new commit.","type":"boolean"},"dismissal_restrictions":{"description":"Specify which users and teams 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":{"teams":{"description":"The list of team `slug`s with dismissal access","items":{"type":"string"},"type":"array"},"users":{"description":"The list of user `login`s with dismissal access","items":{"type":"string"},"type":"array"}},"type":"object"},"require_code_owner_reviews":{"description":"Blocks merging pull requests until [code owners](https://docs.github.com/articles/about-code-owners/) review them.","type":"boolean"},"required_approving_review_count":{"description":"Specify the number of reviewers required to approve pull requests. Use a number between 1 and 6.","type":"integer"}},"type":"object"},"required_status_checks":{"description":"Require status checks to pass before merging. Set to `null` to disable.","nullable":true,"properties":{"checks":{"description":"The list of status checks to require in order to merge into this branch.","items":{"properties":{"app_id":{"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.","type":"integer"},"context":{"description":"The name of the required check","type":"string"}},"required":["context"],"type":"object"},"type":"array"},"contexts":{"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.\n","items":{"type":"string"},"type":"array"},"strict":{"description":"Require branches to be up to date before merging.","type":"boolean"}},"required":["strict","contexts"],"type":"object"},"restrictions":{"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.","nullable":true,"properties":{"apps":{"description":"The list of app `slug`s with push access","items":{"type":"string"},"type":"array"},"teams":{"description":"The list of team `slug`s with push access","items":{"type":"string"},"type":"array"},"users":{"description":"The list of user `login`s with push access","items":{"type":"string"},"type":"array"}},"required":["users","teams"],"type":"object"}},"required":["required_status_checks","enforce_admins","required_pull_request_reviews","restrictions"],"type":"object"}
```

## Responses

### `200`

Response

### `application/json`

- Type: `object`

Branch protections protect branches

```json
{"description":"Branch protections protect branches","properties":{"allow_deletions":{"additionalProperties":false,"properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"type":"object"},"allow_force_pushes":{"additionalProperties":false,"properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"type":"object"},"enforce_admins":{"additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"url":{"format":"uri","type":"string"}},"required":["url","enabled"],"type":"object"},"required_conversation_resolution":{"additionalProperties":false,"properties":{"enabled":{"type":"boolean"}},"type":"object"},"required_linear_history":{"additionalProperties":false,"properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"type":"object"},"required_pull_request_reviews":{"properties":{"dismiss_stale_reviews":{"type":"boolean"},"dismissal_restrictions":{"properties":{"teams":{"items":{"$ref":"#/components/schemas/team"},"type":"array"},"teams_url":{"format":"uri","type":"string"},"url":{"format":"uri","type":"string"},"users":{"items":{"$ref":"#/components/schemas/simple-user"},"type":"array"},"users_url":{"format":"uri","type":"string"}},"required":["url","users_url","teams_url","users","teams"],"type":"object"},"require_code_owner_reviews":{"type":"boolean"},"required_approving_review_count":{"type":"integer"},"url":{"format":"uri","type":"string"}},"required":["url"],"type":"object"},"required_signatures":{"properties":{"enabled":{"example":true,"type":"boolean"},"url":{"example":"https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_signatures","format":"uri","type":"string"}},"required":["url","enabled"],"type":"object"},"required_status_checks":{"$ref":"#/components/schemas/status-check-policy"},"restrictions":{"$ref":"#/components/schemas/branch-restriction-policy"},"url":{"format":"uri","type":"string"}},"required":["url"],"title":"Protected Branch","type":"object"}
```

### `403`

Forbidden

### `application/json`

- Type: `object`

Basic Error

```json
{"description":"Basic Error","properties":{"documentation_url":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"title":"Basic Error","type":"object"}
```

### `404`

Resource not found

### `application/json`

- Type: `object`

Basic Error

```json
{"description":"Basic Error","properties":{"documentation_url":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"title":"Basic Error","type":"object"}
```

### `422`

Validation failed

### `application/json`

- Type: `object`

Validation Error Simple

```json
{"description":"Validation Error Simple","properties":{"documentation_url":{"type":"string"},"errors":{"items":{"type":"string"},"type":"array"},"message":{"type":"string"}},"required":["message","documentation_url"],"title":"Validation Error Simple","type":"object"}
```

## Request examples

### cURL

```shell
curl --request PUT \
  --url {protocol}://{hostname}/api/v3/repos/{owner}/{repo}/branches/{branch}/protection \
  --header 'content-type: application/json' \
  --data '{
  "allow_deletions": true,
  "allow_force_pushes": true,
  "enforce_admins": true,
  "required_conversation_resolution": true,
  "required_linear_history": true,
  "required_pull_request_reviews": {
    "bypass_pull_request_allowances": {
      "teams": [
        "justice-league"
      ],
      "users": [
        "octocat"
      ]
    },
    "dismiss_stale_reviews": true,
    "dismissal_restrictions": {
      "teams": [
        "justice-league"
      ],
      "users": [
        "octocat"
      ]
    },
    "require_code_owner_reviews": true,
    "required_approving_review_count": 2
  },
  "required_status_checks": {
    "contexts": [
      "continuous-integration/travis-ci"
    ],
    "strict": true
  },
  "restrictions": {
    "apps": [
      "super-ci"
    ],
    "teams": [
      "justice-league"
    ],
    "users": [
      "octocat"
    ]
  }
}'
```