The Combined Status API is official

We're happy to announce that the Combined Status API is officially part of the GitHub API v3. We now consider it stable for production use.

Thanks to everyone who provided feedback during the comment period. We got some great feedback, and hope this feature helps you build the tools you need to make GitHub the best place to ship exactly the way you want.

Preview media type no longer needed

If you used the Combined Status API during the preview period, you needed to provide a custom media type in the Accept header:

application/vnd.github.she-hulk-preview+json

Now that the preview period has ended, you no longer need to pass this custom media type.

Instead, we recommend that you specify v3 as the version in the Accept header:

application/vnd.github.v3+json

Feedback

We'll never be done listening to you! As always, please don't hesitate to share your feedback.

New example webhook payloads

Today, we’ve added example webhook payloads to the event types page. Alongside existing descriptions for each event, we now include an example payload so that you can quickly see the data provided by the event. You can learn more about how webhooks work with our Webhooks Guide.

If you have any questions or feedback, please get in touch.

The GitHub Enterprise API documentation has a new home!

GitHub Enterprise offers the same set of APIs as GitHub.com, as well as its own set of Enterprise-specific functionality.

The GitHub Enterprise API has been documented on the Enterprise Help for some time. We've now moved the resources to this site to be hosted alongside the rest of the GitHub API documentation.

Is there an API workflow you're particularly interested in? Let us know and we'll do our best to write a guide!

Pagination in the Combined Status API

We're getting close to bringing the Combined Status API out of preview mode, and have just a couple of small changes to make before it's .

First, we're now paginating combined status API calls. The combined status state field will always take all statuses into account, but we'll now only return 100 embedded statuses at a time.

Second, we're adding a total_count field, mirroring the Search API. This count represents the number of contexts submitted for the given commit.

As always, we're interested in hearing your feedback.

Improved CI support for the Deployments API

Today we're making a few minor changes to the Deployments API preview. With the introduction of combined statuses in a recent update, we noticed a few inconsistencies with the API that we'd like to remedy.

We're introducing a new parameter called required_contexts. This parameter accepts an array of named commit status contexts that are ensured to be in a "success" state before the deployment is created. This allows you to verify that more than one system verified your code before you deploy it.

We've removed support for the force parameter. The force parameter existed to bypass both the auto-merge and commit status checks. The same behavior can now be accomplished by setting auto_merge and required_contexts appropriately.

We're also setting a context for all commit statuses. If a commit status is created without a context, we'll now set it to the string "default".

If you have any questions or concerns, drop us a line.

New attributes for PullRequestReviewComment events

We've enhanced the PullRequestReviewComment events payloads to include action and pull_request attributes. With the addition of the pull_request attribute, you now have immediate access to detailed information about the pull request without needing an additional API request.

If you have any questions or feedback, please get in touch.

New attributes for the Deployments API

We're continuing to iterate on the Deployments API preview, and we're starting to see it satisfy more and more use cases. Today we're introducing new attributes for Deployments and Deployment Statuses as well as a few payload changes.

This is a breaking change for Deployment Status payloads. If you're trying out this new API during its preview period, you'll need to update your code to continue working with it.

API Changes

For Deployments we're introducing the concept of an environment. An environment is basically a unique identifier for a deployment target. Lots of people tend toward the concept of environments for staging, QA, user acceptance testing, etc. We hope this enhancement will enable more use cases for our users that deploy to multiple environments.

Deployments are also persisting the requested deployment ref. Previously we resolved a ref to the current SHA for that ref. Now we'll be keeping the ref around for historical purposes. This is especially helpful if you're deploying branches to verify them before you merge them into your default branch (e.g., "master").

JSON Payload Changes

We're also adding a few attributes to the outbound Deployment payloads. We're now including the ref attribute so you know the branch or tag name that resolved to a specific SHA. The environment is also present.

Webhook Changes

The Deployment Status payloads now embed the associated Deployment object. With this enhancement, Deployment Status events received via webhooks will have enough information to notify other systems, without having to call back to the GitHub API for the environment, ref, or payload that was deployed.

Example Deployment JSON

{
  "url": "https://api.github.com/repos/my-org/my-repo/deployments/392",
  "id": 392,
  "sha": "837db83be4137ca555d9a5598d0a1ea2987ecfee",
  "ref": "master",
  "environment": "staging",
  "payload": {
    "fe": [
      "fe1",
      "fe2",
      "fe3"
    ]
  },
  "description": "ship it!",
  "creator": {
    "login": "my-org",
    "id": 521,
    "avatar_url": "https://avatars.githubusercontent.com/u/2988?",
    "type": "User"
  },
  "created_at": "2014-05-09T19:56:47Z",
  "updated_at": "2014-05-09T19:56:47Z",
  "statuses_url": "https://api.github.com/repos/my-org/my-repo/deployments/392/statuses"
}

Example Deployment Status JSON

{
  "url": "https://api.github.com/repos/my-org/my-repo/deployments/396/statuses/1",
  "id": 1,
  "state": "success",
  "deployment": {
    "url": "https://api.github.com/repos/my-org/my-repo/deployments/396",
    "id": 392,
    "sha": "837db83be4137ca555d9a5598d0a1ea2987ecfee",
    "ref": "master",
    "payload": {
      "fe": [
        "fe1",
        "fe2",
        "fe3"
      ]
    },
    "environment": "production",
    "description": "Deploying to production",
    "creator": {
      "login": "alysson-goldner",
      "id": 540,
      "type": "User"
    },
    "created_at": "2014-05-09T19:59:36Z",
    "updated_at": "2014-05-09T19:59:36Z",
    "statuses_url": "https://api.github.com/repos/my-org/my-repo/deployments/396/statuses"
  },
  "description": "Deployment succeeded",
  "target_url": "https://deploy.myorg.com/apps/my-repo/logs/420",
  "created_at": "2014-05-09T19:59:39Z",
  "updated_at": "2014-05-09T19:59:39Z",
  "deployment_url": "https://api.github.com/repos/my-org/my-repo/deployments/396"
}

If you have any questions or feedback, please get in touch.

Improved pagination for the Repository Commits API

The Repository Commits API now supports an additional approach for paginating commit lists. As of today, this endpoint supports the "standard" page and per_page parameters for controlling pagination. This API now uses these parameters by default when constructing page links.

Improved results and increased consistency

This new approach improves the reliability of this endpoint, which on rare occasions skipped some commits during pagination. This enhancement also increases the overall consistency of the API, as all endpoints now paginate resource lists the same way.

Old parameters still supported

The old way of paginating, using top, last_sha, and per_page parameters, is still supported in API v3, but it will be removed in the next major version of the API. API clients that are manually constructing URLs for pages should be modified to use the new parameters. Even better, API clients shouldn't construct URLs for pages manually, but should use page links provided by the Link header in API responses.

Since both the new and the old pagination parameters are still supported in API v3, API clients shouldn't notice any changes today. Still, if you notice any problems with this endpoint, please let us know.

Changes to Gist API response for large files

In order to provide a faster, more robust API for Gist, we are making two changes to better handle large files in Gist API responses.

Truncating file contents larger than one megabyte

The Gist API response includes data for every file in the Gist. That works well for Gists with reasonably-sized files. When a Gist contains large files, however, it can lead to timeouts when preparing or sending the API response.

To eliminate those timeouts, the API now limits the amount of content returned for each file. If a file is larger than one megabyte in size, the API response will include the first megabyte of content for that file. (Few Gists have files this large. As a result, most API clients won't notice any impact from this change.)

New "truncated" attribute

The JSON snippet below illustrates the attributes provided for each file in the Gist API response. In it, you'll notice a new truncated attribute included as part of the file metadata. This Boolean attribute indicates whether the content value is truncated for this request.

{
  files: {
    "my_large_file.md": {
      "size": 2097152,
      "content": "Large content. Truncated at end of first megabyte. [...]",
      "truncated": true,
      "raw_url": "https://raw.githubusercontent.com/[...]/my_large_file.md",
      "type": "text/plain",
      "language": "Markdown"
    }
  }
}

Getting the full content for truncated files

We recognize that sometimes you'll still want the full content for a file, even if it's too large to get returned in the standard Gist API response. For files under 10 megabytes, simply make a request to the URL specified in the raw_url attribute, and you'll receive the complete content for that file. For larger files, you'll need to clone the gist locally via the git_pull_url to access the full file contents.

If you have any questions, don’t hesitate to get in touch.

New user content domains

Securing your content

The GitHub Bug Bounty program recently identified a few cross-domain vulnerabilities related to user-generated content, and we've shipped improvements today to address those issues.

In order to better isolate your content from potentially malicious content uploaded by other users (e.g., content that might contain Cross-Site Scripting or other embedded attacks), we now serve user-generated content from subdomains of githubusercontent.com. This content is no longer served from subdomains of github.com.

What's affected?

This change affects the following subdomains:

• raw.github.com : Serves raw file content from your repository.
• embed.github.com : Allows users to embed rich GitHub content on other sites.
• render.github.com : Displays rich content on GitHub.com.
• f.cloud.github.com : Hosts all those amazing gifs you use in Pull Requests and Issues.

Content formerly served by these subdomains is now served from subdomains of githubusercontent.com.

Older links

If you have old links to this content, don't worry: as of today, we're forcing the old domains to redirect to the new domains. Your existing links should continue to work automatically in your browser. If you're using a URL from Gist or GitHub to directly access user-generated content via curl, wget, or a library (like HTTParty), be sure to configure that tool to follow the redirect.

Your proxies or filters

Some security systems (web proxies, for example) may not recognize the githubusercontent.com domain. In those cases, you may need update your proxies and security software accordingly.

As always, if you have any questions, please get in touch.

Happy and safe GitHubbing!