kind:change

title:Protected Branches API Preview Period

created_at:2015-11-11

author_name:nakajima

We're starting a preview period for the[protected branches](https://github.com/blog/2051-protected-branches-and-required-status-checks) API. Protecting a branch prevents force-pushes to it as well as deleting it. You can also specify required status checks that are required to merge code into the branch.

To protect a branch, make a`PATCH` request to the URL of the branch:

{:.terminal}

curl "https://api.github.com/v3/repos/github/hubot/branches/master"\

-XPATCH\

-H 'Authorization: token TOKEN'

-H "Accept: application/vnd.github.loki-preview"\

-d "{\"protection\":{\"enabled\":true,\"required_status_checks\":{\"enforcement_level\":\"everyone\",\"contexts\":[\"required-status\"]}}}"\

To access this functionality during the preview period, you’ll need to provide the following custom media type in the Accept header:

Take a look at[the docs here](/v3/repos/#enabling-and-disabling-branch-protection).

If you have any questions, please[get in touch](https://github.com/contact?form%5Bsubject%5D=Protected+Branches+API+Preview).

Name | Type | Description

-----|------|-------------

`protected`|`string` | Set to`1` or`true` to only return protected branches.

{{#tip}}

<aname="preview-period"></a>

The`protected` parameter is currently available for developers to preview.

During the preview period, the API may change without advance notice.

Please see the[blog post](/changes/2015-11-11-protected-branches-api) for full details.

To access the API during the preview period, you must provide a custom[media type](/v3/media) in the`Accept` header:

The`protection` key will only be present in branch payloads if this header is passed.

{{/tip}}

<%= headers 200,:pagination => default_pagination_rels %>

{{#tip}}

<aname="preview-period"></a>

The Protect Branch API is currently available for developers to preview.

During the preview period, the API may change without advance notice.

Please see the[blog post](/changes/2015-11-11-protected-branches-api) for full details.

To access the API during the preview period, you must provide a custom[media type](/v3/media) in the`Accept` header:

The`protection` key will only be present in branch payloads if this header is passed.

{{/tip}}

<%= headers 200 %>

<%= json(:branch) %>

{{#tip}}

<aname="preview-period"></a>

The Protect Branch API is currently available for developers to preview.

During the preview period, the API may change without advance notice.

Please see the[blog post](/changes/2015-11-11-protected-branches-api) for full details.

To access the API during the preview period, you must provide a custom[media type](/v3/media) in the`Accept` header:

{{/tip}}

Protecting a branch requires admin access.

You need to pass a`protection` object.

Name | Type | Description

-----|------|-------------

`enabled`|`boolean` |**Required**. Should this branch be protected or not

`required_status_checks`|`object`| Configure required status checks here

The`required_status_checks` object must have the following keys:

Name | Type | Description

-----|------|-------------

`enforcement_level`|`string` |**Required**. Who required status checks apply to. Options are`off`,`non_admins` or`everyone`.

`contexts`|`array` |**Required**. The list of required status checks to require in order to merge into this branch

The`enforcement_level` key can have the following values:

Name | Description

------|------------

`off` | Turn off required status checks for this branch.

`non_admins` | Required status checks will be enforced for non-admins.

`everyone` | Required status checks will be enforced for everyone (including admins)

<%= json\

"protection" => {

"enabled" => true,

"required_status_checks" => {

"enforcement_level" => "everyone",

"contexts" =>["continuous-integration/travis-ci"]

}

}

%>

Deleting a repository requires admin access. If OAuth is used, the

BRANCH ||={"name"=>"master",