Merge pull request github#897 from github/update-1447279351

hubot · hubot · commit 113553e2c811 · 2015-11-11T14:02:37.000-08:00
diff --git a/content/changes/2015-11-11-protected-branches-api.md b/content/changes/2015-11-11-protected-branches-api.md
@@ -0,0 +1,29 @@
+---
+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\"]}}}" \
+
+#### How can I try it?
+
+To access this functionality during the preview period, you&rsquo;ll need to provide the following custom media type in the Accept header:
+
+```
+application/vnd.github.loki-preview+json
+```
+
+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).
diff --git a/content/v3/repos.md b/content/v3/repos.md
@@ -255,6 +255,28 @@ List languages for the specified repository. The value on the right of a languag
 
     GET /repos/:owner/:repo/branches
 
+### Parameters
+
+Name | Type | Description
+-----|------|-------------
+`protected`|`string` | Set to `1` or `true` to only return protected branches.
+
+{{#tip}}
+
+  <a name="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:
+
+      application/vnd.github.loki-preview+json
+
+  The `protection` key will only be present in branch payloads if this header is passed.
+
+{{/tip}}
+
 ### Response
 
 <%= headers 200, :pagination => default_pagination_rels %>
@@ -266,9 +288,81 @@ List languages for the specified repository. The value on the right of a languag
 
 ### Response
 
+{{#tip}}
+
+  <a name="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:
+
+      application/vnd.github.loki-preview+json
+
+  The `protection` key will only be present in branch payloads if this header is passed.
+
+{{/tip}}
+
 <%= headers 200 %>
 <%= json(:branch) %>
 
+## Enabling and disabling branch protection
+
+{{#tip}}
+
+  <a name="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:
+
+      application/vnd.github.loki-preview+json
+
+{{/tip}}
+
+Protecting a branch requires admin access.
+
+    PATCH /repos/:owner/:repo/branches/:branch
+
+### Input
+
+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)
+
+#### Example
+
+<%= json \
+  "protection" => {
+    "enabled" => true,
+    "required_status_checks" => {
+      "enforcement_level" => "everyone",
+      "contexts" => ["continuous-integration/travis-ci"]
+    }
+  }
+%>
+
 ## Delete a Repository
 
 Deleting a repository requires admin access.  If OAuth is used, the
diff --git a/lib/resources.rb b/lib/resources.rb
@@ -357,11 +357,25 @@ def fetch_content(key)
         "commit" => {
           "sha" => "6dcb09b5b57875f334f61aebed695e2e4193db5e",
           "url" => "https://api.github.com/repos/octocat/Hello-World/commits/c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc"
+        },
+        "protection" => {
+          "enabled" => false,
+          "required_status_checks" => {
+            "enforcement_level" => "off",
+            "contexts" => []
+          }
         }
       }
     ]
 
     BRANCH ||= {"name"=>"master",
+      "protection" => {
+        "enabled" => false,
+        "required_status_checks" => {
+          "enforcement_level" => "off",
+          "contexts" => []
+        }
+      },
  "commit"=>
   {"sha"=>"7fd1a60b01f91b314f59955a4e4d4e80d8edf11d",
    "commit"=>
