Ping Event for Webhooks

With the release of our new webhook UI, we included a new ping event that webhooks will receive. When you create a new webhook, we will send this event as an initial test of the webhook.

The ping is only informational, doesn't need to be responded to in a specific way, and nothing bad will happen if you respond with an error. It's just a quick "hello world" to let you know you set everything up correctly.

We also added a ping endpoint to the hooks API. By using ping instead of test, you can ensure you won't be limited by the push event requirement that the test endpoint has.

Audit organization members for two-factor authentication

We've added a new filter for listing members of an organization without two-factor authentication enabled:

curl -H "Authorization: token [yours]" \
       "https://api.github.com/orgs/[orgname]/members?filter=2fa_disabled"

The new filter is available for owners of organizations with private repositories. Happy auditing and send us your feedback or questions.

Preview the New Deployments API

Today we're excited to announce a Deployments API. We ship a lot of software at GitHub: web, mobile, and native. For the last few years, we've been driving our deployments from our ChatOps tooling and we've learned a lot. The Deployments API is a generalization of the approach that we've been taking, and we're really excited to see what our users and integrations start building around it.

Deployments are a new model in the GitHub ecosystem. We don't have any UI components currently, and deployments are intended to be used exclusively by tooling. If you're familiar with the Status API, you know that it allows various tools to report on the status of a commit (e.g., the progress of an attempt to perform a build at a particular commit). The Status API doesn't perform the build; it just reports the results. Much like the Status API, we won't be doing actual deployments for you. Instead, the API provides a way for you to track the status of your deployments. We're hoping to provide consistency across the various type of release processes, regardless of the underlying steps involved with getting your code built or shipped to your servers.

Highlights

Automatic Merging

The system can auto-merge the default branch for the repository if the requested deployment ref is behind the default branch. On active projects it's easy to fall behind, so let automation watch your back.

Commit Status Integration

By default, the system rejects deployment requests for repositories that have commit statuses but don't have a green build for the deployment ref. This can be bypassed, but is useful in cases where continuous integration is being used.

Force Deployments

Sometimes the world crashes down on you, and you need to just get the code out the door. Forced deployments bypass any commit status checks or ahead/behind checks in the repository.

Deployment Statuses

Different deployment systems can update the status of a deployment to be pending, success, failure, or error. There's also a field for linking to deployment output.

Events

Both Deployments and Deployment Statuses trigger events on GitHub. 3rd party integrations can listen for these events via webhooks and choose whether or not to actually deploy the repository that the event was created for.

Preview Period

We're making this new API available today for developers to preview. We think developers and existing integrations are going to love it, but we want to get your feedback before we declare the Deployments API "final" and "unchangeable." We expect the preview period to last for roughly 60-90 days.

As we discover opportunities to improve the API during the preview period, we may ship changes that break clients using the preview version of the API. We want to iterate quickly. To do so, we will announce any changes here (on the developer blog), but we will not provide any advance notice.

At the end of preview period, the Deployments API will become an official component of GitHub API v3. At that point, the new Deployments API will be stable and suitable for production use.

We hope you’ll take it for a spin and send us your feedback.

Upcoming Change to Default Media Type

On April 15, 2014*, the GitHub API will start serving the v3 media type by default. The information below will help you determine whether your applications will be affected by this change. For affected applications, you'll find tips below to help you smoothly navigate this change.

What's changing?

A new default version

There are two versions of the GitHub API: beta and v3. Today, requests receive the beta version by default. On April 15*, requests will begin receiving the v3 version by default.

For the most part, beta and v3 are remarkably similar. There are just a few differences to keep in mind.

A new default media type

The version is one part of the media type. By default, the API provides the beta media type:

application/vnd.github.beta+json

On April 15*, requests will begin responding with the v3 media type by default:

application/vnd.github.v3+json

Who is affected?

Since 2012, we have encouraged developers to explicitly request a specific media type via the Accept header. If you are requesting either beta or v3 via the Accept header, then you are not affected by this change. The API will continue to respond with the requested media type.

If you are not requesting beta or v3 via the Accept header, then the API is currently responding with the beta media type. On April 15*, the API will begin responding with the v3 media type. If your application relies on functionality that differs between beta and v3, then you are affected by this change. You will need to take steps to prepare for the change.

What should you do?

If you are affected by this change, we recommend that you:

1. Update your applications to depend on the v3 functionality instead of the beta functionality. (If you use one of the popular client libraries, there's a good chance that they've already done the work for you. In that case, you can just update to the latest version of that library.)
2. Request the v3 media type via the Accept header.

If you cannot update your application to depend on the v3 functionality by April 15*, you can just request the beta media type via the Accept header. Doing so will insulate you from this change.

Cutover test on March 12, 2014

To help you understand the impact of this change before it becomes permanent, we will temporarily implement this change for a single day on March 12. From approximately 12:01am UTC to 11:59pm UTC on March 12, the API will respond with the v3 media type by default.

Follow @GitHubAPI to receive updates before and after the test.

Stay informed

Depending on the results of the cutover test, we may schedule additional tests before the final cutover on April 15. If so, we'll to announce them in advance. Be sure to stay tuned to the blog or follow @GitHubAPI for updates.

If you have any questions, please get in touch. We'll be happy to help.

Paginated results for organization members

The [organization members][members] and [organization public members][public members] methods will soon return paginated results by default. Beginning today, these methods will paginate if you include page or per_page query parameters. Starting January 15th, 2014, these methods will always return paginated results.

As always, be sure and follow those [Link headers][paginating] to get subsequent results. If you have any questions or run into trouble, feel free to get in touch.

Happy paginating.

[members]: /v3/orgs/members/#list-organization-members[public members]: /v3/orgs/members/#list-public-organization-members[paginating]: /v3/#pagination

Releases API is Official

Hot on the heels of the Search API, the Releases API is now officially part of GitHub API v3. We now consider it stable for production use.

Preview Media Type No Longer Needed

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

application/vnd.github.manifold-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

Onward!

Thanks again to everyone that tried out the Releases API during the preview period. We got some great feedback, and we are already discussing additions to the API.

We can't wait to see what you ship!

Search API Becomes an Official Part of API v3

We're excited to announce that the new Search API has graduated from preview mode. As of today, the Search API is an official part of GitHub API v3. As such, the Search API is now stable and suitable for production use.

Preview Media Type No Longer Needed

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

application/vnd.github.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

Onward!

Thanks again to everyone that tried out the Search API during the preview period.

We can't wait to see what you build!

New Validation Rule for Beta Code Search API

As we prepare to end the preview period for the new search API, we're making sure that it's ready to handle the traffic from all the apps you'll build on top of it.

New Validation Rule

In order to support the expected volume of requests, we're applying a new validation rule to the Code Search API. Starting today, you will need to scope your code queries to a specific set of users, organizations, or repositories.

As usual, you specify the query via the q parameter. The value must include at least one user, organization, or repository.

For example, with this query, we're searching for code from @twitter or @facebook that uses an MIT License:

MIT License user:twitter user:facebook

And here, we're looking for uses of the underscore library in @mozilla's BrowserQuest repository:

underscore language:js repo:mozilla/BrowserQuest

To perform these queries via the API, we would use the following URLs (respectively):

https://api.github.com/search/code?q=MIT+License+user%3Atwitter+user%3Afacebook

https://api.github.com/search/code?q=underscore+language%3Ajs+repo%3Amozilla%2FBrowserQuest

All the various code search qualifiers are still available to you. A user, organization, or repository qualifier is now required. The other search qualifiers are still optional.

Other Search Types Not Affected

This new validation only applies to the Code Search API. It does not apply to the Search API for issues, users, or repositories.

This validation does not affect searches performed on github.com/search.

By ensuring that code queries are more targeted in nature, the API will be ready to meet the expected demand from all your apps. As we continue to tune the Search API, we hope to relax this validation in the future. There's no ETA, but we'd like to relax it as soon as it's feasible.

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

List all teams for the authenticated user

We just added a List teams for the authenticated user endpoint to list all the teams for the authenticated user across all organizations:

curl -H "Authorization: token [yours]" https://api.github.com/user/teams
[
  {
    "name": "Testing",
    "id": 396018,
    "slug": "testing",
   "permission": "pull",
   "url": "https://api.github.com/teams/396018",
   "members_url": "https://api.github.com/teams/396018/members{/member}",
   "repositories_url": "https://api.github.com/teams/396018/repos",
   "members_count": 1,
   "repos_count": 0,
   "organization": {
     "login": "dotfiles",
     "id": 1593590,
     "url": "https://api.github.com/orgs/dotfiles",
     "repos_url": "https://api.github.com/orgs/dotfiles/repos",
     "events_url": "https://api.github.com/orgs/dotfiles/events",
     "members_url": "https://api.github.com/orgs/dotfiles/members{/member}",
     "public_members_url": "https://api.github.com/orgs/dotfiles/public_members{/member}",
     "avatar_url": "https://0.gravatar.com/avatar/67d30facf213f62853c119fc2a05e246?d=https%3A%2F%2Fidenticons.github.com%2Fc90a68e6ab739e81c642f0e93f88c722.png"
   }
 },
 ...
]

As always, if you have any questions or feedback, please drop us a line.

OAuth changes coming

Starting today, we are returning granted scopes as part of the access_token response. For example, if you are making a POST with the application/json mime-type you'll see an additional field for the granted scopes.

{
  "access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a",
  "scope":"repo,gist",
  "token_type":"bearer"
}

Right now, these scopes will be identical to what you requested, but we are moving towards a feature set that will allow GitHub users to edit their scopes, effectively granting your application less access than you originally requested. You should be aware of this possibility and adjust your application behavior accordingly.

Some things to watch out for and keep in mind:

• Most third party applications using GitHub OAuth to identify users have the best success in adoption by starting out with a request for the minimum access that the application can possibly get away with. Something like no scopes or just user:email is very sane.

• It is important to handle the error cases where a user chooses to grant you less access than you originally requested. Now that we are surfacing the granted scopes on the access_token response, applications can warn or otherwise communicate with their users that they will see reduced functionality or be unable to perform some actions.

• Applications can always send users back through the flow again to get additional permission, but don't forget that users can always say no.