Combined status API blog post

Ben Lavender · Ben Lavender · commit 736bf4180ebb · 2014-03-27T11:41:51.000-05:00
diff --git a/Gemfile b/Gemfile
@@ -19,5 +19,5 @@ group :development do
 end
 
 group :test do
-  gem 'html-proofer', '~> 0.6.0'
+  gem 'html-proofer', '~> 0.6.1'
 end
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -10,13 +10,12 @@ GEM
     cri (2.4.1)
       colored (>= 1.2)
     daemons (1.1.9)
-    ethon (0.6.2)
+    ethon (0.7.0)
       ffi (>= 1.3.0)
-      mime-types (~> 1.18)
     eventmachine (1.0.3)
     ffi (1.9.3)
     fssm (0.2.10)
-    html-proofer (0.6.0)
+    html-proofer (0.6.1)
       colored (~> 1.2)
       mercenary (~> 0.2.0)
       nokogiri (~> 1.6.0)
@@ -40,8 +39,8 @@ GEM
       daemons (>= 1.0.9)
       eventmachine (>= 1.0.0)
       rack (>= 1.0.0)
-    typhoeus (0.6.7)
-      ethon (~> 0.6.2)
+    typhoeus (0.6.8)
+      ethon (>= 0.7.0)
     yajl-ruby (0.8.3)
 
 PLATFORMS
@@ -52,7 +51,7 @@ DEPENDENCIES
   builder
   coderay
   fssm
-  html-proofer (~> 0.6.0)
+  html-proofer (~> 0.6.1)
   kramdown (~> 0.13.2)
   mime-types (~> 1.16)
   nanoc (~> 3.4.3)
diff --git a/content/changes/2014-03-27-combined-status-api.md b/content/changes/2014-03-27-combined-status-api.md
@@ -0,0 +1,56 @@
+---
+kind: change
+title: Preview the New Combined Status API
+created_at: 2014-03-27
+author_name: bhuga
+---
+
+What does it mean for a branch to be "green?" The [Status API][status-api] helps
+thousands of teams answer that question. Developers use it to record the status
+of continuous integration builds, contributor license agreements, code coverage
+analysis, automated security testing, dependency management, and more.
+
+For many teams, a branch is considered "green" only when _all_ of their various
+status checks are successful. With the new [Combined Status
+API][combined-status-api], developers can easily fetch this single, consolidated
+status for any branch, commit, or tag.
+
+### Status context
+
+To help multiple service providers use the Status API simultaneously, statuses
+now support a `context` field. This field allows a provider to distinguish its
+statuses from another provider's statuses. For example, your [Jenkins][] builds
+might use a context of `ci/jenkins`, while your [Brakeman][] checks might adopt a
+context of `security/brakeman`.
+
+The new [Combined Status endpoint][combined-status-api] returns a single,
+combined state, as well as the latest status from each context. Systems that
+consume status updates can now get all the information they need in one place.
+
+### Opt-in
+
+The existing [Status API][list-statuses] continues to work as it always has. The
+`context` field is entirely optional, and the [color of the merge button on pull
+requests](https://github.com/blog/1227-commit-status-api) does not currently
+take context into account.
+
+### Preview period
+
+We're making this new API available today for developers to
+[preview][status-api]. During this period, we may change aspects of the Combined
+Status API from time to time. We will announce any changes here (on the
+developer blog), but we will not provide any advance notice.
+
+We expect the preview period to last 30-60 days. At the end of preview period,
+the Combined Status API will become an official component of GitHub API v3. At
+that point, this new API will be stable and suitable for production use.
+
+We hope you'll [try it out][status-api] and [send us your feedback][contact]!
+
+[status-api]: /v3/repos/statuses/
+[contact]: https://github.com/contact?form[subject]=Combined+Status+API
+[combined-status-api]: /v3/repos/statuses/#get-the-combined-status-for-a-specific-ref
+[create-a-status]: /v3/repos/statuses/#create-a-status
+[brakeman]: http://brakemanscanner.org/
+[jenkins]: http://jenkins-ci.org/
+[list-statuses]: /v3/repos/statuses/#list-statuses-for-a-specific-ref
diff --git a/content/program.md b/content/program.md
@@ -6,7 +6,7 @@ layout: developers
 <div class="feature dev-program">
   <div class="wrapper">
     <h1>It takes a community to design, build, and ship great software.</h1>
-    <p class="intro">Building an application that integrates with GitHub? Register for our Developer Program, the possibilities are endless and the kudos is all yours.</p>
+    <p class="intro">Building an application that integrates with GitHub? Register for our Developer Program! The possibilities are endless, and you enjoy the kudos.</p>
     <a href="https://github.com/developer/register" class="button">Register now</a>
   </div>
   <img src="/shared/images/header-animation.gif" alt="GitHub Universe" class="earth" width="450" height="375">
diff --git a/content/v3/repos/deployments.md b/content/v3/repos/deployments.md
@@ -98,9 +98,10 @@ Users with pull access can view deployments for a repository:
 ## Create a Deployment
 
 If your repository is taking advantage of [commit statuses](/v3/repos/statuses),
-the API will reject requests that do not have a success status. (Your repository
-is not required to use commit statuses. If no commit statuses are present, the
-deployment will always be created.)
+the API will reject requests that do not have a successful [combined
+status.](/v3/repos/statuses/#get-the-combined-status-for-a-specific-ref) (Your
+repository is not required to use commit statuses. If no commit statuses are
+present, the deployment will always be created.)
 
 The `force` parameter can be used when you really just need a deployment to go
 out. In these cases, all checks are bypassed, and the deployment is created for
diff --git a/content/v3/repos/statuses.md b/content/v3/repos/statuses.md
@@ -25,18 +25,59 @@ Note that the `repo:status` [OAuth scope](/v3/oauth/#scopes) grants targeted
 access to Statuses **without** also granting access to repository code, while the
 `repo` scope grants permission to code as well as statuses.
 
+## Create a Status
+
+Users with push access can create commit statuses for a given ref:
+
+    POST /repos/:owner/:repo/statuses/:sha
+
+### Parameters
+
+Name | Type | Description
+-----|------|--------------
+`state`|`string` | **Required**. The state of the status. Can be one of `pending`, `success`, `error`, or `failure`.
+`target_url`|`string` | The target URL to associate with this status.  This URL will be linked from the GitHub UI to allow users to easily see the 'source' of the Status.<br/>For example, if your Continuous Integration system is posting build status, you would want to provide the deep link for the build output for this specific SHA:<br/>`http://ci.example.com/user/repo/build/sha`.
+`description`|`string` | A short description of the status.
+`context`|`string` | A string label to differentiate this status from the status of other systems.
+
+#### Example
+
+<%= json \
+  :state         => "success",
+  :target_url    => "https://example.com/build/status",
+  :description   => "The build succeeded!",
+  :context       => "continuous-integration/jenkins"
+%>
+
+### Response
+
+<%= headers 201,
+      :Location =>
+'https://api.github.com/repos/octocat/example/statuses/1' %>
+<%= json :status %>
+
+<% combined_media_type = "application/vnd.github.she-hulk-preview+json" %>
+
 ## List Statuses for a specific Ref
 
 Users with pull access can view commit statuses for a given ref:
 
     GET /repos/:owner/:repo/statuses/:ref
 
+<div class="alert">
+  <p>
+    If you send an <code>Accept</code> header with the Combined Status API preview
+    <a href="/v3/media/">media type</a>, <code><%= combined_media_type %></code>,
+    this endpoint is also available at <code>/repos/:owner/:repo/:ref/status</code>.
+  </p>
+</div>
+
 Statuses are returned in reverse chronological order. The first status in the
 list will be the latest one.
 
 ### Parameters
 
-Name | Type | Description 
+Name | Type | Description
 -----|------|--------------
 `ref`|`string` | **Required**. Ref to list the statuses from. It can be a SHA, a branch name, or a tag name.
 
@@ -46,31 +87,37 @@ Name | Type | Description
 <%= headers 200 %>
 <%= json(:status) { |h| [h] } %>
 
-## Create a Status
+## Get the combined Status for a specific Ref
 
-Users with push access can create commit statuses for a given ref:
+<div class="alert">
+  <p>
+    The Combined status endpoint is currently available for developers to preview.
+    During the preview period, the API may change without advance notice.
+    Please see the <a href="/changes/2014-03-27-combined-status-api/">blog post</a> for full details.
+  </p>
+  <p>
+    To access this endpoint during the preview period, you must provide a custom
+    <a href="/v3/media/">media type</a> in the <code>Accept</code> header:
+    <pre><%= combined_media_type %></pre>
+  </p>
+</div>
 
-    POST /repos/:owner/:repo/statuses/:sha
+Users with pull access can access a combined view of commit statuses for a given ref.
 
-### Parameters
+    GET /repos/:owner/:repo/:ref/statuses
 
-Name | Type | Description 
------|------|--------------
-`state`|`string` | **Required**. The state of the status. Can be one of `pending`, `success`, `error`, or `failure`.
-`target_url`|`string` | The target URL to associate with this status.  This URL will be linked from the GitHub UI to allow users to easily see the 'source' of the Status.<br/>For example, if your Continuous Integration system is posting build status, you would want to provide the deep link for the build output for this specific SHA:<br/>`http://ci.example.com/user/repo/build/sha`.
-`description`|`string` | A short description of the status
+The most recent status for each context is returned (up to 25), as well as a combined
+`state`. The `state` is `pending` to start, `failure` if any status reports as
+`error` or `failure`, `pending` if any context's latest status is `pending`, and
+`success` if the latest status for all contexts is `success`. (`null` is
+considered a distinct context)
 
-#### Example
+### Parameters
 
-<%= json \
-  :state         => "success",
-  :target_url    => "https://example.com/build/status",
-  :description   => "The build succeeded!"
-%>
+Name | Type | Description
+-----|------|--------------
+`ref`|`string` | **Required**. Ref to fetch the status for. It can be a SHA, a branch name, or a tag name.
 
 ### Response
-
-<%= headers 201,
-      :Location =>
-'https://api.github.com/repos/octocat/example/statuses/1' %>
-<%= json :status %>
+<%= headers 200 %>
+<%= json(:combined_status) { |h| [h] } %>
diff --git a/layouts/_meta.html b/layouts/_meta.html
@@ -12,7 +12,7 @@ <h2 class="title">
     <% end %>
   </li>
   <li class="who_when">
-    <%= gravatar_for(@item[:author_name]) %>
+    <%= avatar_for(@item[:author_name]) %>
       <a href="https://github.com/<%= @item[:author_name] %>"><%= @item[:author_name] %></a>
   </li>
 </ul>
diff --git a/lib/resources.rb b/lib/resources.rb
@@ -27,27 +27,6 @@ module Helpers
         502 => '502 Bad Gateway'
       }
 
-      AUTHORS = {
-        :technoweenie => '821395fe70906c8290df7f18ac4ac6cf',
-        :tclem        => '2f4861b27dc35663ed271d39f5358261',
-        :pengwynn     => '7e19cd5486b5d6dc1ef90e671ba52ae0',
-        :pezra        => 'f38112009dc16547051c8ac246cee443',
-        :rick         => 'a44d5abad6e86cff4e34d9f0839535c9',
-        :agh          => '6af915d3c6aa4ad30bbad43d8035fe10',
-        :jasonrudolph => '592e1e6f041f9a4ec51846fd82013aea',
-        :Caged        => '97c3a8eea9b7eaa9e1e93ea3cd47399f',
-        :foca         => 'd0ca2bf32bda9e9ea8c4473ffc3aaa0d',
-        :ymendel      => 'b1b1d33e0655e841d4fd8467359c58d0',
-        :mastahyeti   => '8caa0afdae1a934c30a1998472c63134',
-        :atmos        => 'a86224d72ce21cd9f5bee6784d4b06c7',
-        :kdaigle      => 'dd18bb36fa5f06e45843ff8de33b793e',
-        :gjtorikian   => 'befd819b3fced8c6bd3dba7e633dd068',
-        :izuzak       => 'ff743b4cba28cc47ad65cb90212c1e51',
-        :spicycode    => '7ce90d712fab09421b7f2cf955b9a4c8',
-        :dbussink     => 'b012094b37ab6946c44eaa41d7828478',
-        :benbalter    => '19d03ecc1ff5da1a5e63a3ddaa2d84c2',
-      }
-
       DefaultTimeFormat = "%B %-d, %Y".freeze
 
       def post_date(item)
@@ -58,15 +37,12 @@ def strftime(time, format = DefaultTimeFormat)
         attribute_to_time(time).strftime(format)
       end
 
-      def gravatar_for(login)
-        %(<img height="16" width="16" src="%s" alt="gravatar_for_#{login}"/>) % gravatar_url_for(login)
+      def avatar_for(login)
+        %(<img height="16" width="16" src="%s" alt="Avatar for #{login}"/>) % avatar_url_for(login)
       end
 
-      def gravatar_url_for(login)
-        md5 = AUTHORS[login.to_sym]
-        default = "https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png"
-        "https://secure.gravatar.com/avatar/%s?s=20&d=%s" %
-          [md5, default]
+      def avatar_url_for(login)
+        "https://github.com/#{login}.png"
       end
 
       def headers(status, head = {})
@@ -1589,15 +1565,31 @@ def text_html(response, status, head = {})
       "description" => "Deploy request from hubot",
     }
 
-    STATUS = {
+    SIMPLE_STATUS = {
       "created_at" => "2012-07-20T01:19:13Z",
       "updated_at" => "2012-07-20T01:19:13Z",
       "state" => "success",
       "target_url" => "https://ci.example.com/1000/output",
       "description" => "Build has completed successfully",
       "id" => 1,
       "url" => "https://api.github.com/repos/octocat/example/statuses/1",
+      "context" => "continuous-integration/jenkins"
+    }
+
+    STATUS = SIMPLE_STATUS.merge(
       "creator" => USER
+    )
+
+    COMBINED_STATUS = {
+      "state" => "success",
+      "name"  => "octocat/Hello-World",
+      "sha"   => COMMIT["sha"],
+      "statuses" => [
+        SIMPLE_STATUS.merge("context" => "continuous-integration/jenkins"),
+        SIMPLE_STATUS.merge("context" => "security/brakeman")
+      ],
+      "commit_url" => "https://api.github.com/repos/octocat/Hello-World/#{COMMIT["sha"]}",
+      "repository_url" => "https://api.github.com/repos/octocat/Hello-World"
     }
 
     META = {
