More time to prepare for the breaking changes to organization permissions

After listening to your feedback on the upcoming breaking changes to organization permissions, we’re giving developers more time to update their applications. We’ll announce an updated timeline for these changes in the coming weeks.

In the meantime, if your application relies on any of the affected functionality described in our previous blog post, please update your code to account for these changes. If you have any questions or feedback, please get in touch with us!

Breaking changes to Authorizations API responses on April 20

A couple weeks ago we extended the preview period of several API changes related to managing OAuth application authorizations. Today, we’re finalizing these changes. This new functionality is now stable and suitable for production use. If your application relies on any of the affected functionality (described below), be sure to update your code before April 20 to account for these changes.

Breaking changes coming on April 20

If your application uses any of the following APIs, then you may be affected by this change:

• The List your authorizations API
• The Get a single authorization API
• The Get-or-create an authorization for a specific app API (token is still returned for “create”)
• The Get-or-create an authorization for a specific app and fingerprint API (token is still returned for “create”)
• The Update an existing authorization API

If your application uses these APIs, we urge you to update your application as soon as possible. (Read the December announcement for more details on the changes.)

Starting today, we’re offering a migration period allowing applications to opt in to these changes (as described below). On April 20, these changes will become official parts of the GitHub API v3. At that time, these changes will apply to all API consumers.

Migration period

During the migration period, you can opt-in to these changes using the following custom media type in the Accept header:

application/vnd.github.mirage-preview+json

We want to make these updates as smooth as possible for everyone, and we hope that the migration period gives you flexibility to adopt these changes on your own schedule. If you have any questions or feedback, please get in touch with us!

New Releases API methods

We’ve added two new methods to the Releases API. You can now get the latest published release for a repository.

GET /repos/:owner/:repo/releases/latest

You can also get a release by tag name.

GET /repos/:owner/:repo/releases/tags/:tag

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

Removing token attribute from Authorizations API responses (Update)

In December, we released a preview of several API changes related to managing OAuth application authorizations. As part of those changes we introduced several new response attributes (token_last_eight, hashed_token, and fingerprint) to the Authorizations API. We have decided to modify hashed_token to return the SHA-256 hex digest of the associated token instead of Base64. Given that Base64 has several common variants (original, URL safe, etc) we decided that returning the value as hex is less ambiguous and will be more useful for developers.

Extended preview period

Because of the change to hashed_token, we are extending the preview period by two weeks. If no additional changes are made during this extended preview period we will announce the end of the preview and beginning of the eight week migration period on February 17. The migration period will allow applications to opt in to these changes before they become an official part of the GitHub API v3.

If you have any questions or feedback, please drop us a line!

An integrator's guide to organization application policies

As we announced over on the GitHub blog, organization admins can now control how third-party applications access their organization data. Allowing admins to approve or deny applications will ultimately result in deeper trust and increase overall adoption of integrations within organizations on GitHub.

As an integrator, here’s what you need to know about organization application policies and how this feature could impact your application.

Guiding principles

We’ve tried to strike the right balance between organization privacy and the user experience for integrators and end users. Organizations should be able to prevent applications they do not trust from accessing their organization data without creating a multitude of new edge cases for integrators.

With that goal in mind, the feature works like this: if an organization’s application policy prevents an application from accessing its resources, the API behaves as if the authenticating user is not a member of the organization. Specifically, this means an application authenticating on behalf of a user using OAuth will have:

• Read-only access to public resources. Organization-owned public repositories, issues, and other resources will be visible via the API and show up in resource listings, but mutating methods (POST, PATCH, PUT, and DELETE) will return status 403.
• No access to private resources. Organization-owned private repositories, issues, and other resources will not be visible via the API and will not show up in resource listings that co-mingle public and private resources. Hooks for these private repositories are muted and will not be delivered as long as the application is restricted by the organization.

Since applications should already handle the scenario where a user loses access to organization resources, this reduces the work integrators need to do.

Checking organization access

As organization admins adopt application whitelists and restrict third-party application access to organization resources, your application may lose access to those resources. If an organization member is not aware of the new access policy, they may wonder why their private repositories or other resources no longer work or show up in your application.

There are a couple ways to help troubleshoot access for your end users.

• Via the GitHub UI. The simplest way to help end users understand how organization access policies affect their access to your application is to provide a link to their authorization details under their GitHub account settings as described in the OAuth documentation.

• Via the API. For an even better user experience, use the API to list which user organizations your application can access, and provide users with the link mentioned above to request access from their organization admins.

Listing accessible organization resources

In addition to checking access to a user’s organizations, you’ll want to ensure you’re discovering their accessible resources in the most efficient way. Recent changes to the Respositories API might reduce the API calls your application needs to make to find a user’s repositories across all of their organization mememberships.

Ensuring uninterrupted SSH access

Since applications should already handle the scenario where a user loses access to organization resources (e.g., when a user leaves an organization), this reduces the work integrators need to do. Keys created by OAuth applications (or those created before GitHub started tracking that information) will not have access to repositories owned by organizations that restrict third-party applications. If your application uses keys created before February 24, 2014, you should replace those older keys to ensure things keep running smoothly for your application.

We’re here to help

This is a big feature, and we’re sure it will impact many of our integrators as organizations adopt third-party application restrictions. We also think it provides a huge net benefit for integrators as organizations choose to use OAuth integrations with more confidence.

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

New guide: Discovering resources for a user

Is your application taking advantage of the recommended workflow for discovering a user’s repositories and organizations? With the recent improvements to the API, the process is simpler than ever. In our newest guide, we show you how to reliably identify the resources that your app can access for a given user.

If you have any questions or feedback, we’d love to hear from you.

Prepare for upcoming organization permissions changes

Last month, we released a preview of several API changes related to managing organization members and repositories. Today, we’re finalizing these changes. This new functionality is now stable and suitable for production use. If your application relies on any of the affected functionality (described below), be sure to update your code before February 24 to account for these changes.

Breaking changes coming on February 24

If your application uses any of the following APIs, then you are affected by this change:

• APIs for managing your organization’s admins through the Owners team
• The List your repositories API
• The List your organizations API
• The List user organizations API

If your application uses these APIs, we urge you to update your application as soon as possible. (Read last month’s announcement for more details on the changes.)

Starting today, we’re offering a migration period allowing applications to opt in to these changes (as described below). On February 24, these changes will become official parts of the GitHub API v3. At that time, these changes will apply to all API consumers.

Migration period

During the migration period, you can opt-in to these changes using the following custom media type in the Accept header:

application/vnd.github.moondragon+json

We want to make these updates as smooth as possible for everyone, and we hope that the migration period gives you flexibility to adopt these changes on your own schedule. If you have any questions or feedback, please get in touch with us!

Replace older SSH keys created by your application

Back in February, we improved the security audit trail for SSH keys. Soon, organizations will be able to block access for SSH keys that were created prior to those improvements. If your application relies on deploy keys or user keys for repository access, we recommend replacing any keys created before February 24, 2014.

To ensure that your application is not affected by organizations blocking access to these keys, you should replace the affected keys by January 15, 2015.

How should you replace these keys?

We recommend the following steps for identifying and replacing the affected keys.

1. Identify the affected keys

You only need to replace keys that your application created prior to February 24, 2014. If you don’t know when your app created a given key, you can get the creation timestamp from the API. The created_at property is available for deploy keys and for user keys.

2. Inform the affected users

Once you know which keys you need to replace, we recommend that you inform the affected users.

For security, GitHub automatically sends an email to a user whenever a new SSH key is added to their account. Similarly, when a new deploy key is added to a repository, GitHub sends an email to the repository’s administrators. When you replace your application’s old keys with new ones, GitHub will email the affected users. To avoid surprising those users, you should alert them that you’ll be replacing your keys. You may want to include a link to this post in your message.

3. Add a new key

Use the API to add the new deploy key or user key.

4. Delete the old key

Once your application is using the new key, use the API to delete the old one. There’s an API for deleting deploy keys and an API for deleting user keys.

We’re here to help

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

New Attributes for Starring API

You can now see when a user starred a repository. To receive the new response format containing the starred_at field, request the new media type:

curl -H "Accept: application/vnd.github.v3.star+json" https://api.github.com/users/andrew/starred

Note the starred repository is now available in the repo field.

Feedback

If you have any questions or feedback about these changes, please drop us a line.

Preview the upcoming organization permission changes

UPDATE (2014-12-12): The List your organizations API is now included in this preview as well.

We have some upcoming changes that will affect the way organization members and repositories are managed. The most important changes are:

• The Owners team will no longer be special.
• The List your repositories API will include organization-owned repositories.
• The List user organizations API will only include public organization memberships.
• The List your organizations API will require user scope or read:org scope.

What’s happening to the Owners team?

Currently, members of your Owners team are administrators of your organization. Soon, your Owners team will become a totally normal team. Adding and removing Owners team members won’t change their administrator status anymore. Instead, you’ll be able to directly grant admin permissions to your organization’s members without adding them to any special teams.

We won’t delete your Owners team, but you’ll be able to delete or rename it yourself if you want. Organizations created after the change won’t have an Owners team.

What should you do?

In preparation for this change to the Owners team, we’re releasing a few new APIs. You’ll be able to use these APIs to manage organization admins without relying on the Owners team.

Adding an organization admin

To add a new organization admin, use the new Add or update organization membership endpoint, specifying a role of "admin" in the request body. This replaces adding or inviting people to the Owners team.

Removing an organization admin

To remove someone from the organization role but keep them as a member of their teams, use the new Add or update organization membership endpoint, specifying a role of "member" in the request body. This replaces removing people from the Owners team.

Listing organization admins

To get a list of all your organization’s admins, use the Organization members list endpoint, specifying a role of "admin" in the query string. This replaces listing the members of the Owners team.

Checking if someone is an organization admin

To check if a given user is an organization admin, use the new Get organization membership endpoint. If the returned "role" attribute is set to "admin" and the returned "state" attribute is set to "active", the user is an organization admin. This replaces checking if a user is on the Owners team.

What’s happening to the “List your repositories” API?

Currently, the List your repositories API only returns repositories that are owned by users, not by organizations. If you want a list of all the repositories that the authenticated user has access to, you need to use multiple API methods.

Soon, this API will include all repositories that the authenticated user has access to (whether they’re owned by a user or by an organization).

What should you do?

Many apps use the List your repositories API in conjunction with the List your organizations and List organization repositories APIs to build up a list of all the repositories the authenticated user has access to. If your app is doing this, you’ll be able to get rid of all the organization-related API calls and just use the List your repositories API.

If your app uses the List your repositories API for another purpose, you’ll need to update your app to handle the new organization-owned repositories we’ll be returning.

What’s happening to the “List user organizations” API?

The List user organizations API is intended provide public organization memberships for any user. When you use this API to fetch your own organizations, this API currently returns your public and private organization memberships.

Soon, this API will only return public organization memberships.

What should you do?

If your app uses the List user organizations API to fetch all of the organization memberships (public and private) for the authenticated user, you’ll need to update your app to use the List your organizations API instead. The List your organizations API returns all organizations (public and private) that your app is authorized to access.

What’s happening to the “List your organizations” API?

OAuth requests will soon require minimum scopes in order to access the List your organizations API.

Currently, the API response always includes your public organization memberships, regardless of the OAuth scopes associated with your request. If you have user, read:org, write:org, or admin:org scope, the response also includes your private organization memberships.

Soon, this API will only return organizations that your authorization allows you to operate on in some way (e.g., you can list teams with read:org scope, you can publicize your organization membership with user scope, etc.). Therefore, this API will require at least user or read:org scope. (write:org and admin:org scope implicitly include read:org scope.) OAuth requests with insufficient scope will receive a 403 Forbidden response.

What should you do?

If you authenticate via username and password, you are not affected by this change.

If your app only needs to fetch the user’s public organization memberships, you should use the List user organizations API instead. Since that API only returns public information, it does not require any scopes.

Preview period

Starting today, these new APIs are available for developers to preview. We expect the preview period to last for four weeks. (Stay tuned to the developer blog for updates.) At the end of the preview period, these additions will become official components of the GitHub API.

While these additions are in their preview period, you’ll need to provide the following custom media type in the Accept header:

application/vnd.github.moondragon-preview+json

During the preview period, we may change aspects of these endpoints. If we do, we will announce the changes on the developer blog, but we will not provide any advance notice.

Migration period

At the end of the preview period, we will announce the start of a migration period. At that time, developers should update their applications to use the new APIs for managing organization admins. During this period, you will still be able to use the Owners team to manage your organization’s admins, so that you have time to update your applications to use the new APIs without breakage. We expect the migration period to last for four weeks.

At the end of the migration period, the Owners team will no longer be special, and you’ll no longer be able to rely on it for managing organization admins.

If you have any questions or feedback, please get in touch with us!

Removing token attribute from Authorizations API responses

Since OAuth access tokens function like passwords, they should be treated with care. Today we are making it easier to more securely work with authorizations via the Authorizations API. We are deprecating the use use of the token attribute in the majority of the Authorizations API responses. For the affected APIs, the token attribute will soon return an empty string. To get ready for that change, we are giving developers a chance to preview the updated API starting today.

What’s changing?

The current OAuth Authorizations API requires GitHub to store the full value for each OAuth token on our servers. In order to increase the security for our users, we are changing our architecture to store the SHA-256 digest of OAuth tokens instead. GitHub securely hashes user passwords using bcrypt and we want to provide comparable security for OAuth tokens as well.

Rest assured that this change is an entirely proactive measure from GitHub and is not associated with any security incident.

Who is affected?

This change affects any code that relies on accessing the token attribute from these OAuth Authorizations API responses. For example, our own GitHub for Mac and GitHub for Windows applications relied on reading the token from the Get-or-create an authorization for a specific app API, in order to support multiple installations of our desktop application for a single user.

What should you do?

In order to reduce the impact of removing the token attribute, the OAuth Authorizations API has added a new request attribute (fingerprint), added three new response attributes (token_last_eight, hashed_token, and fingerprint), and added one new API. While these new APIs and attributes do not replace the full functionality that previously existed, they can be used in place of token for most common use cases.

• token_last_eight returns the last eight characters of the associated OAuth token. As an example, token_last_eight could be used to display a list of partial token values to help a user manage their OAuth tokens.

• hashed_token is the base64 of the SHA-256 digest of the token. hashed_token could be used to programmatically validate that a given token matches an authorization returned by the API.

• fingerprint is a new optional request parameter that allows an OAuth application to create multiple authorizations for a single user. fingerprint should be a string that distinguishes the new authorization from others for the same client ID and user.

  For example, to differentiate installations of a desktop application across multiple devices you might set fingerprint to SHA256_HEXDIGEST("GitHub for Mac - MAC_ADDRESS_OF_MACHINE"). Since fingerprint is not meant to be a user-facing value, you should still set the note attribute to help a user differentiate between authorizations on their OAuth applications listing on GitHub.

• Get-or-create an authorization for a specific app and fingerprint is a new API that is analagous to the Get-or-create an authorization for a specific app API, but adds support for the new fingerprint request parameter.

Preview period

We are making the new Authorizations API available today for developers to preview. During this period, we may change aspects of these endpoints. If we do, we will announce the changes on the developer blog, but we will not provide any advance notice.

While these new APIs are in their preview period, you’ll need to provide the following custom media type in the Accept header:

application/vnd.github.mirage-preview+json

We expect the preview period to last 4-6 weeks. (Stay tuned to the developer blog for updates.) At the end of the preview period, these changes will become an official and stable part of GitHub API.

Migration period

At the end of the preview period, we will announce the start of a migration period. Developers will have 8 weeks to update existing code to use the new APIs.

Why SHA-256 over bcrypt?

Some users may be curious why we are not using bcrypt to hash our OAuth tokens like we do for user passwords. Bcrypt is purposefully computationally expensive in order to mitigate brute force attacks against low entropy passwords. However, OAuth tokens are highly random and are not susceptible to brute force attacks. Given that OAuth token validation occurs for each request to the API we chose SHA-256 for performance reasons.

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

Preview the New Organization Webhooks API

Today we’re very excited to announce Organization Webhooks. Organization Webhooks allow you to subscribe to events that happen across an entire organization.

In addition to being able to subscribe to the existing repository oriented events across an organization, we’re also adding some new events which are exclusive to organization webhooks. The new repository event allows you to receive webhook payloads when a new repository is created. By subscribing to the membership event, you’ll be notified whenever a user is added or removed from a team.

We’re making this new API for Organization Webhooks available today for developers to preview. The preview period will allow us to get your feedback before declaring the Organization Webhooks API final. We expect the preview period to last for roughly 30-60 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 Organization Webhooks API will become an official component of GitHub API v3. At that point, the new Organization Webhooks API will be stable and suitable for production use.

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

The Deployments API is official

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

Thanks to everyone who provided feedback during the preview 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 Deployments API during the preview period, you needed to provide a custom media type in the Accept header:

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

Status API Limits

To ensure a high level of service for all API consumers, we will soon limit the number of statuses to 1000 per commit SHA, repository, and context.

Beginning Monday, November 3rd, we will trim existing data sets that exceed this limit, deleting the oldest records first. Attempts to create statuses beyond that limit will result in a validation error.

If you have any feedback or questions, please don’t hesistate to contact us.

Deployment webhook payload changes

On November 4th, 2014, we will begin sending a new format for deployment and deployment status payloads for webhooks. In the meantime we’ll be running in a compatability mode that will give integrators the time needed to start taking advantage of the new format. Integrators who are working with webhooks and deployments are advised to upgrade to the new payload format to avoid service interruption.

This change brings the payloads for these events more inline with the responses you’d receive from the API. Instead of having deployment and deployment status attributes as top-level keys, we will now nest them under deployment and deployment_status keys. Since we’re still in the preview period for the deployments API we felt it was best to correct this inconsistency now.

DeploymentEvent Changes

Old Format

{
  "id": 42,
  "sha": "deadbeef",
  "ref": "master",
  "task": "deploy",
  "name": "my-org/our-app",
  "environment": "production",
  "payload": {…},
  "description": "Deploying master",
  "repository": {…},
  "sender": {…}
}

Current Format - 2014/10/22

{
  "id": 42,
  "sha": "deadbeef",
  "ref": "master",
  "task": "deploy",
  "name": "my-org/our-app",
  "environment": "production",
  "payload": {…},
  "description": "Deploying master",
  "repository": {…},
  "deployment": {
    "url": "https://api.github.com/repos/my-org/our-app/deployments/42",
    "id": 42,
    "sha": "deadbeef",
    "ref": "master",
    "task": "deploy",
    "environment": "production",
    "payload": {…},
    "description": "Deploying master",
    "creator": {…},
    "created_at": "2014-09-23T16:37:49Z",
    "updated_at": "2014-09-23T16:37:49Z",
    "statuses_url": "https://api.github.com/repos/my-org/our-app/deployments/42/statuses"
  },
  "sender": {…}
}

New Format - 2014/11/05

{
  "deployment": {
    "url": "https://api.github.com/repos/my-org/our-app/deployments/42",
    "id": 42,
    "sha": "deadbeef",
    "ref": "master",
    "task": "deploy",
    "environment": "production",
    "payload": {…},
    "description": "Deploying master",
    "creator": {…},
    "created_at": "2014-09-23T16:37:49Z",
    "updated_at": "2014-09-23T16:37:49Z",
    "statuses_url": "https://api.github.com/repos/my-org/our-app/deployments/42/statuses"
  },
  "repository": {…},
  "sender": {…}
}

DeploymentStatusEvent Changes

Old Format

{
  "id": 2600,
  "state": "success",
  "deployment": {…},
  "target_url": "https://gist.github.com/deadbeef",
  "description": "Deployment was successful",
  "repository": {…},
  "sender": {…}
}

Current Format - 2014/10/22

{
  "id": 2600,
  "state": "success",
  "target_url": "https://gist.github.com/deadbeef",
  "description": "Deployment was successful",
  "repository": {…},
  "deployment_status": {
    "url": "https://api.github.com/repos/my-org/our-app/deployments/42/statuses2600",
    "id": 2600,
    "state": "success",
    "creator": {…},
    "target_url": "https://gist.github.com/deadbeef",
    "description": "Deployment was successful",
    "created_at": "2014-09-23T16:45:49Z",
    "updated_at": "2014-09-23T16:45:49Z",
    "deployment_url": "https://api.github.com/repos/my-org/our-app/deployments/42",
    "repository_url": "https://api.github.com/repos/my-org/our-app"
  },
  "deployment": {…},
  "sender": {…}
}

New Format - 2014/11/05

{
  "deployment_status": {
    "url": "https://api.github.com/repos/my-org/our-app/deployments/42/statuses2600",
    "id": 2600,
    "state": "success",
    "creator": {…},
    "target_url": "https://gist.github.com/deadbeef",
    "description": "Deployment was successful",
    "created_at": "2014-09-23T16:45:49Z",
    "updated_at": "2014-09-23T16:45:49Z",
    "deployment_url": "https://api.github.com/repos/my-org/our-app/deployments/42",
    "repository_url": "https://api.github.com/repos/my-org/our-app"
  },
  "deployment": {…},
  "repository": {…},
  "sender": {…}
}

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

Removed SSLv3 support from webhooks and services

This morning, we removed support for the ssl_version webhook configuration option and made TLS 1.X the default cryptographic protocol to address the POODLE exploit. You should no longer set or rely on the ssl_version configuration option.

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

New Attributes for Issue Events API

We’ve made it easier to track changes to issues. The Issue Events API now provides more context for several event types:

• assigned and unassigned events now include an assignee object so you can see just who was assigned or unassigned.
• labeled and unlabeled events include a label object.
• milestoned and demilesoned events include a milestone object.
• renamed events include a rename object with the title before and after the rename.

Check out the Issue Events API documentation for a full list of supported events. If you have any questions or feedback, please drop us a line.

One more week before the "Add team member" API breaking change

UPDATE (2014-09-30): In response to feedback from developers, we’re delaying the breaking change to the “Add team member” API until Monday, October 6, 2014. The change will go into effect for all requests on that date.

Starting October 6, if you use the “Add team member” API to add a user to a team and that user isn’t already on another team in your organization, the request will fail. To avoid this, be sure to use the the “Add team membership” API.

The Organization and Team Membership APIs are now official

As promised in our blog post earlier this month, the Organization Membership and Team Membership APIs are now an official part of the GitHub API! The preview media type is no longer required to access them.

If you have any questions or feedback, please get in touch with us!

Finalizing the Organization and Team Membership APIs

For the past few weeks, the new Organization Membership and Team Membership APIs have been available for early access via a preview media type. As of today, these APIs are stable and suitable for production use.

Preview period ends on September 23

On September 23, 2014, these APIs will become official parts of the GitHub API v3. At that time, the preview media type will no longer be required to access these APIs.

Reminder: Breaking change to legacy endpoint

The breaking change to the “Add team member” endpoint will also go into effect for all requests on September 23, 2014. At that time, if you use the add team member endpoint to add a user to a team and that user isn’t already on another team in your organization, the request will fail. To avoid this, be sure to use the add team membership endpoint.

Addition to the Organization Membership API

Thanks to your feedback, we’ve updated the Organization Membership API to provide direct access to basic information about the organization whenever you fetch a list of memberships or a single membership.

If you have any questions or feedback, please get in touch with us!

Changing organization feeds in the Feeds API

We have deprecated the current_user_organization_url attribute and the current_user_organization.href attribute in the Feeds API. If you make use of these attributes, you’ll want to update your code to use the new current_user_organization_urls attribute instead.

Changes to the deprecated attributes

Previously, the deprecated attributes returned URI template. For example:

"current_user_organization_url":
  "https://github.com/organizations/{org}/mastahyeti.private.atom?token=abc123"

The template included a deprecated authentication token. Our new tokens are valid only for a concrete feed URL (not for a URI template). Because the deprecated attributes were templates and did not specify a concrete URL, the API could not provide a token that could be used for organization feeds.

Starting today, the API returns empty values for the deprecated attributes.

New attribute for organization feeds

In order to preserve the functionality of this API, we have added a new attribute that lists specific Atom feed urls for each of the user’s organizations.

"current_user_organization_urls": [
  "https://github.com/organizations/github/mastahyeti.private.atom?token=abc123"
  "https://github.com/organizations/requests/mastahyeti.private.atom?token=token=def456"
]

Check out the updated Feeds API documentation for the new fields. If you have any questions or feedback, please get drop us a line.

Removing Gravatar ID from user payloads

We have deprecated the gravatar_id attribute in the user representation. Starting September 19, the API will always provide an empty string as the value for this attribute.

Users have been able to upload avatars directly to GitHub for a while now. If users haven’t uploaded an avatar, we still try to fetch one from Gravatar, but that happens behind the scenes on GitHub’s servers. As a result, the gravatar_id attribute no longer identifies a GitHub user’s canonical avatar. Instead, API consumers should use the avatar_url to fetch a user’s avatar. The avatar_url attribute has always been present in the v3 user representation and is the only reliable way to find a GitHub user’s avatar.

If you have any questions or feedback, please get drop us a line.

Accepting organization invitations from the API

The upcoming Team Memberships API gives you the power to invite new GitHub users to your organization via the API. We’re expanding the API to also allow users to view their organization membership statuses and accept any invitations they’ve received.

The new Organization Memberships API

When someone invites you to an organization, your membership with that organization begins in the “pending” state. The new list organization memberships endpoint allows you to find your pending memberships. You can then change them to “active” (accepting the invitation in the process) by using the edit organization membership endpoint.

New Team Membership API response attribute

Previously, responses from the add team membership and get team membership endpoints included a “status” attribute, which could either be “active” or “pending”. We’ve renamed this attribute from “status” to “state” for better consistency with our other API calls.

To give you time to update your apps, we’ll keep the legacy “status” attribute around alongside the new “state” attribute until September 4th, 2014.

Preview period

The new Organization Memberships API is available for developers to preview alongside the Team Memberships API. During this period, we may change aspects of these endpoints. If we do, we will announce the changes on the developer blog, but we will not provide any advance notice.

While these new APIs are in their preview period, you’ll need to provide the following custom media type in the Accept header:

application/vnd.github.the-wasp-preview+json

We expect the preview period to last 30-60 days. At the end of the preview period, the Team and Organization Memberships APIs will become official components of GitHub API v3.

If you have any questions or feedback, please get in touch with us!

New features for the Deployments API preview

We’ve added two new features to the Deployments API preview: the ability to query deployments and a new task attribute for different types of deployment tasks.

API changes

You can now search for deployments via query parameters to the listing endpoint. You can filter on sha, ref, task, and environment. This makes it easier to answer questions like “when was the last time someone deployed to staging?”

$ curl -H "Authorization: token [yours]" \
       https://api.github.com/repos/octocat/my-repo/deployments?environment=staging

New attribute

We’ve also added a task attribute to the deployment resource. The task attribute allows you to specify tasks other than just pushing code. Popular deployment tools like capistrano and fabric support named tasks to do things like running schema migrations. We hope this attribute will give integrators the flexibility they need to provide custom functionality.

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

We're changing the way you add new members to your organization

Today, we’re announcing a change to the way organization owners add new members to their organization.

Previously, if you were an organization owner, you could use the add team member endpoint to add any GitHub user to any team on your organization without any sort of approval from them. Now, we’re increasing user security by sending invitations to users when they’re added to teams on organizations that they aren’t yet a part of.

With this change, if you use the add team member endpoint to add a user to a team and that user isn’t already on another team in your organization, the request will fail.

The new Team Memberships API

You should change all your add team member requests to use the new add team membership endpoint. This new endpoint works exactly the same as the old one, with one important change: if the membership being added is for a user who is unaffiliated with the team’s organization, that user will be sent an invitation via email.

Unlike the add team member endpoint, a successful request to the add team membership endpoint does not guarantee that the user is now a member of the team. If you’re trying to migrate to the new endpoint and need to know when a user has been successfully added (not just invited) to a team, please check out TeamAddEvent.

Preview period

We’re making the new Team Memberships API (and the breaking changes to the add team member API) available today for developers to preview. During this period, we may change aspects of these endpoints. If we do, we will announce the changes on the developer blog, but we will not provide any advance notice.

While these new APIs are in their preview period, you’ll need to provide the following custom media type in the Accept header:

application/vnd.github.the-wasp-preview+json

We expect the preview period to last 30-60 days. At the end of the preview period, the Team Memberships API will become an official component of GitHub API v3, as will the add team member API’s breaking changes.

If you have any questions or feedback, please get in touch with us!

New assigned/labeled actions for issue and pull request events

As part of the new GitHub Issues, we’ve added new actions to the issues and pull requests webhook events: “labeled”, “unlabeled”, “assigned”, and “unassigned”. The payload will also include the respective assignee or label for these new actions.

If you already have a webhook subscribed to the issues or pull_request events, you’ll start seeing these new actions immediately. The new events can also be fetched from the issue events API.

For more information, be sure to check out our documentation for the IssuesEvent or PullRequestEvent. If you have any questions or feedback, please drop us a line.

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 site 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 :sparkles:.

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!

Deprecating the beta media type

Now that the GitHub API is serving the v3 media type by default, we are deprecating the legacy beta media type.

We will eventually remove support for the beta media type, but we have no official retirement date to annouce at the moment. When the time comes, rest assured that we’ll announce the retirement with plenty of notice. In the meantime, existing API clients that rely on the beta media type should start making plans to migrate to v3. The beta media type differs from v3 in just a few places. In most cases, migrating an application from the beta media type to the v3 media type is smooth and painless.

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

Extending the preview period for the Deployments API

The preview period for the new Deployments API continues to yield valuable feedback from developers. In early March, we used that feedback to improve the payload format that integrations can use to customize deployments. A few weeks later, we began integrating with the new Combined Status API to help ensure that only verified code gets deployed, even if you have multiple systems verifying different aspects of your software.

To give developers time to explore these recent refinements to the Deployments API, we’re extending the preview period for a little while longer. As always, if you have any questions or feedback, please get in touch.

Reminder: Default media type will change on April 15

Just a friendly reminder: On April 15, 2014, the GitHub API will start serving the v3 media type by default. Please see the original announcement for full details about this change, who it affects, and how to ensure that you are prepared.

If you have any questions, please get in touch.

Recommendation: Reset OAuth authorizations

As announced earlier today, we are actively responding to the recently-disclosed Heartbleed security vulnerability in OpenSSL. While at this time GitHub has no indication that the attack has been used beyond testing the vulnerability, we recommend that integrators reset the API authorizations for their OAuth applications.

We’ve added a new API method for this exact purpose. Calling this method will invalidate the old token and return a new token for applications to store and use in its place. This new method provides a safe way to reset user authorizations without requiring users to re-authorize the application on the web.

Integrators can also use the existing revocation methods to revoke all tokens or revoke a single token for their applications.

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

Understanding search results and potential timeouts

Some queries are computationally expensive for our search infrastructure to execute. To keep the Search API fast for everyone, we limit how long any individual query can run. In rare situations when a query exceeds the time limit, the API returns all matches that were found prior to the timeout.

Starting today, the Search API also now informs you when such a timeout happens. Reaching a timeout does not necessarily mean that search results are incomplete. It just means that the query was discontinued before it searched through all possible data. More results might have been found, but also might not.

In some cases, if you know that your search results are potentially incomplete, you might think about the data differently. By exposing timeouts when they happen, the API helps you better understand how to interpret the results.

We hope this is useful as you integrate with the Search API. In the meantime, we’re working on improving search so that these timeouts occur as rarely as possible. If you have any questions, let us know.

Grant access to create public repositories without granting access to private repositories

The Create Repository method now allows creating public repositories via OAuth with public_repo scope. This means you can safely grant third party applications the ability to create public repositories on your behalf without granting access to your private repositories.

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

Preview the New Combined Status API

What does it mean for a branch to be “green?” The 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, 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 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 continues to work as it always has. The context field is entirely optional, and the color of the merge button on pull requests does not currently take context into account.

Preview period

We’re making this new API available today for developers to preview. 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 and send us your feedback!

Pagination changes for some resource lists

In an effort to keep the API fast for everyone, we’re enabling pagination on some API methods that previously did not support it. Beginning today, the methods below will paginate if you include page or per_page query parameters. Starting April 17th, 2014, these methods will always return paginated results. If you have any questions or run into trouble, feel free to get in touch.

Here’s the complete list of updated methods:

Gist comments

GET /gists/:gist_id/comments

Gist commits

GET /gists/:gist_id/commits

Gist forks

GET /gists/:gist_id/forks

Git refs

GET /repos/:owner/:repo/git/refs

Issue labels

GET /repos/:owner/:repo/issues/:number/labels

Milestone labels

GET /repos/:owner/:repo/milestones/:id/labels

Organization teams

GET /orgs/:org/teams

Pull Request commits

GET /repos/:owner/:repo/pulls/:number/commits

Pull Request files

GET /repos/:owner/:repo/pulls/:number/files

Release assets

GET /repos/:owner/:repo/releases/:id/assets

Repository collaborators

GET /repos/:owner/:repo/collaborators

Repository contributors

GET /repos/:owner/:repo/contributors

Repository branches

GET /repos/:owner/:repo/branches

Repository downloads

GET /repos/:owner/:repo/downloads

Repository keys

GET /repos/:owner/:repo/keys

Repository labels

GET /repos/:owner/:repo/labels

Repository tags

GET /repos/:owner/:repo/tags

Repository teams

GET /repos/:owner/:repo/teams

Team members

GET /teams/:id/members

Team repositories

GET /teams/:id/repos

User emails (v3 media type only)

GET /user/emails

User keys

GET /users/:user/keys
GET /user/keys

Page Build Event for Webhooks

We’ve made it even easier to track the status of your GitHub Pages builds. By subscribing to the new page_build event, your application will receive an event payload containing the results of each build. (As always, these builds occur automatically following each push to a GitHub Pages-enabled branch.)

If you have a webhook with the “send me everything” option selected (or if you use the “wildcard event” via the API), you will receive the page_build event after the next build of your GitHub Pages site. Alternatively, if you prefer to subscribe to specific event types, you can add to the new page_build event to your webhooks via your repository’s webhook settings page or via the webhooks API.

For more information, be sure to check out our guide on working with webhooks. If you have any questions or feedback, please drop us a line.

Reminder: March 12 Cutover Test for Default Media Type

In January, we announced an upcoming change to the default media type. To help developers assess the impact of that change before it becomes permanent, we’re performing a 24-hour cutover test next week.

From approximately 12:01am UTC to 11:59pm UTC on March 12, the API will respond with the v3 media type by default. (See the start time for the cutover test in your time zone.)

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

Please see the original announcement for full details. If you have any questions, please get in touch.

Improved timezone handling in the API

We have improved support for handling timezones in our API. For example, if you create commits through the API, we now allow for specifying timezone information more accurately.

We apply the following rules, in order of priority, to determine timezone information for API calls:

Explicitly provide an ISO 8601 timestamp with timezone information

For API calls that allow for a timestamp to be specified, we use that exact timestamp. An example of this is the Commits API which allows for specifying the date property.

{
  "message": "my commit message",
  "author": {
    "name": "Dirkjan Bussink",
    "email": "d.bussink@gmail.com",
    "date": "2014-02-27T15:05:06+01:00"
  },
  "parents": [
    "7d1b31e74ee336d15cbd21741bc88a537ed063a0"
  ],
  "tree": "827efc6d56897b048c772eb4087f854f46256132"
}

Using the Time-Zone header

It is possible to supply a Time-Zone header which defines a timezone according to the list of names from the Olson database.

$ curl -H "Time-Zone: Europe/Amsterdam" -X POST https://api.github.com/repos/github/linguist/contents/new_file.md

This means that we generate a timestamp for the moment your API call is made in the timezone this header defines. For example, the Contents API generates a git commit for each addition or change and uses the current time as the timestamp. This header will determine the timezone used for generating that current timestamp.

Using the last known timezone for the user

If no Time-Zone header is specified and you make an authenticated call to the API, we use the last known timezone for the authenticated user. The last know timezone is updated whenever you browse the GitHub.com website.

UTC

If the steps above don’t result in any information, we use UTC as the timezone to create the git commit.

If you have any questions or feedback, don’t hesitate to contact us!

New Payload Format for Deployments

As we iterate on the preview for the new Deployments API, we’re making sure that it’s friendly to work with for the apps built on top of it.

Deserialize Deployment Payloads

To make the API even easier to use, we’ll now return your custom payload as a JSON object along with the rest of the Deployment resource. No need to parse it as JSON again.

Code You Need to Update

You should only need to remove the JSON parsing if you’re taking advantage of the custom payloads. The formats for creating Deployments remain unchanged.

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

Query enhancements for listing issues and pull requests

We’ve made it even easier to list all issues and pull requests via the API. The state parameter now supports a value of all that will return issues and pull requests regardless of state.

$ curl https://api.github.com/repos/atom/vim-mode/issues\?state\=all

We’ve also introduced new sorting options for listing pull requests. You can now sort pull requests by created, updated, popularity, and long-running.

$ curl https://api.github.com/repos/rails/rails/pulls\?sort\=long-running\&direction\=desc

Happy querying. If you have any questions or feedback get in touch.

OAuth scopes for organization and team resources

As a follow up to the new scopes we announced yesterday, we’ve introduced even more OAuth scopes for working with organization and team resources:

• read:org provides read-only access to organizations, teams, and membership.
• write:org allows an application to publicize and unpublicize an organization membership.
• admin:org enables an application to fully manage organizations, teams, and memberships.

Check out the full list of OAuth scopes supported by the API to ensure your application asks for only the permissions it needs. As always, if you have any questions or feedback, get in touch.

Wildcard Event for Webhooks

We’ve made a small change to make it easier for webhook integrators to receive “everything”. Instead of adding every event to your webhook, you can now opt-in to all events (including all new events in the future) by using the wildcard event (*).

If you add this event to an existing webhook, we’ll remove the existing specific events and send you payloads for all supported events. As we add new events, you’ll automatically begin receiving those too.

Finer-grained OAuth scopes for SSH keys

As we announced, we’ve made some important changes to the way that API consumers manage SSH keys.

Finer-grained OAuth scopes

To help third party applications request only permissions that they need, the API now supports three new scopes for working with a user’s public SSH keys.

• read:public_key provides read access to the user’s SSH keys
• write:public_key allows an app to read existing keys and create new ones
• admin:public_key enables an app to read, write, and delete keys

Changes to user scope

Historically, user scope has provided full access to manage a user’s SSH keys. Now that we have dedicated scopes for managing a user’s SSH keys, we have removed those permissions from the user scope. Now user scope will no longer provide access to SSH keys. Applications that need this access should request one of the new scopes described above.

Keys are now immutable

To simplify the security audit trail for SSH keys, we’re making keys immutable. API consumers can continue to create keys and delete keys as needed, but keys can no longer be changed. To change an existing key, API consumers should delete the existing key and create a new one with the desired attributes. This change applies both to a user’s SSH keys and a repository’s deploy keys.

Deleting keys when revoking a token

Also any keys created via an OAuth token from this point forward will be deleted when that token is revoked.

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

Gist raw file URI change

The raw host for all Gist files is changing immediately. This change was made to further isolate user content from trusted GitHub applications. The new host is https://gist.githubusercontent.com. Existing URIs will redirect to the new host.

Repository Contributors and Empty Repositories

We’ve made a small change to the Repository Contributors API in the way empty repositories are handled. Previously, the API returned a 404 Not Found status when the list of contributors was fetched for an empty repository. To improve consistency with other API endpoints and reduce confusion, the API now returns a 204 No Content status instead.

If you notice any strangeness, just let us know.

Introducing the Pages API

We’ve created a new API to GitHub Pages. This API is accessible by owners of a Pages repo, whether it’s owned by an individual or an organization.

With the Pages API, you can get information about your site, as well as details on previous Pages builds.

Enjoy!

New scopes for managing repository hooks

Many third party services need to set up hooks in order to act upon events in your repositories. Today, we’ve introduced three new scopes that provide more granular access to your repository hooks without allowing access to your repository contents:

• read:repo_hook grants read and ping access to hooks in public or private repositories.
• write:repo_hook grants read, write, and ping access to hooks in public or private repositories.
• admin:repo_hook grants read, write, ping, and delete access to hooks in public or private repositories.

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

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 and organization 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 to get subsequent results. If you have any questions or run into trouble, feel free to get in touch.

Happy paginating.

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 new API method 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.

An Update on the New Search API

We owe a big “Thank You!” to everyone that has taken the time to try out the new Search API. We :heart: every one of you. Just as we hoped, the preview period has allowed us to see how you want to use the new API, and it has given us a chance to improve the API before finalizing it.

In order to incorporate everything that we’ve learned, we’re going to keep the Search API in preview mode for a little while longer. We have a few bugs to squash and a couple performance kinks to iron out. We’re hard at work on those improvements now, and we expect to have more news in the coming weeks.

In the mean time, keep the suggestions coming!

Releases API

This summer we made it easier to release your software. Today, you can fully automate those releases via the Releases API Preview.

This API is a little different due to the binary assets. We use the Accept header for content negotiation when requesting a release asset. Pass a standard API media type to get the API representation:

$ curl -i -H "Authorization: token TOKEN" \
     -H "Accept: application/vnd.github.manifold-preview" \
     "https://uploads.github.com/repos/hubot/singularity/releases/assets/123"

HTTP/1.1 200 OK

{
  "id": 123,
  ...
}

Pass “application/octet-stream” to download the binary content.

$ curl -i -H "Authorization: token TOKEN" \
     -H "Accept: application/octet-stream" \
     "https://uploads.github.com/repos/hubot/singularity/releases/assets/123"

HTTP/1.1 302 Found

Uploads are handled by a single request to a companion “uploads.github.com” service.

$ curl -H "Authorization: token TOKEN" \
     -H "Accept: application/vnd.github.manifold-preview" \
     -H "Content-Type: application/zip" \
     --data-binary @build/mac/package.zip \
     "https://uploads.github.com/repos/hubot/singularity/releases/123/assets?name=1.0.0-mac.zip"

Preview mode

The new API is available as a preview. This gives developers a chance to provide feedback on the direction of the API before we freeze changes. We expect to lift the preview status in 30 days.

As with the Search API, we’ll take this opportunity to iterate quickly. Breaking changes will be announced on this developer blog without any advance warning. Once the preview period is over, we’ll consider the Releases API unchangeable. At that point, it will be stable and suitable for production use.

The preview media type is “application/vnd.github.manifold-preview”. Manifold is a member of the Avengers, with the ability to teleport through time and space. He’s the one in the middle holding the spear.

Two-Factor Authentication and the API

As announced earlier today, GitHub.com now supports two-factor authentication (2FA) for increased security. For users with this feature enabled, GitHub.com will prompt for a 2FA code in addition to a username and password during authentication. We’ve also rolled out some improvements to the API to ensure that 2FA requirements in the API are consistent with GitHub.com.

Authenticating with the API

For users without 2FA enabled, and for applications using the OAuth web flow for authentication, everything is business as usual. You’ll continue to authenticate with the API just as you always have. (That was easy.)

If you enable 2FA and use Basic Authentication to access the API, we’re providing multiple options to make the flow simple and easy.

Basic Authentication and 2FA

Personal Access Tokens

Personal access tokens provide the simplest option for using 2FA with Basic Authentication. You can create these tokens via the application settings page on GitHub.com, and you can revoke them at any time. For more information about authenticating to the API with personal access tokens, be sure to check out our help article on the topic.

Tightly-integrated 2FA

For developers wishing to integrate GitHub 2FA directly into their application, the API’s Basic Authentication now supports the ability to send the user’s 2FA code, in addition to the username and password.

We’re here to help

We think GitHub users are going to love the additional security provided by two-factor authentication. As always, if you have any questions or feedback, let us know. We’re here to help!

Improvements to the Search API

Today we’re shipping two improvements to the new Search API.

More Text Match Metadata

When searching for code, the API previously provided text match metadata (i.e., “highlights”) for file content. Now, you can also get this metadata for matches that occur within the file path.

For example, when searching for files that have “client” in their path, the results include this match for lib/octokit/client/commits.rb:

{
  "name": "commits.rb",
  "path": "lib/octokit/client/commits.rb",
  "text_matches": [
    {
      "object_url": "https://api.github.com/repositories/417862/contents/lib/octokit/client/commits.rb?ref=8d487ab06ccef463aa9f5412a56f1a2f1fa4dc88",
      "object_type": "FileContent",
      "property": "path",
      "fragment": "lib/octokit/client/commits.rb",
      "matches": [
        {
          "text": "client",
          "indices": [ 12, 18 ]
        }
      ]
    }
  ]
  // ...
}

Better Text Match Metadata

Before today, the API applied HTML entity encoding to all fragment data. For example, imagine your search returns an issue like rails/rails#11889:

The response would include a text_matches array with the following object:

{
  "fragment": "undefined method `except' for #<Array:XXX>",
  // ...
}

Inside the fragment value, we see HTML-encoded entities (e.g., <). Since we’re returning JSON (not HTML), API clients might not expect any HTML-encoded text. As of today, the API returns these fragments without this extraneous encoding.

{
  "fragment": "undefined method `except' for #<Array:XXX>",
  // ...
}

Preview Period

We’re about halfway through the preview period for the new Search API. We appreciate everyone that has provided feedback so far. Please keep it coming!

Preview the New Search API

Today we’re excited to announce a brand new Search API. Whether you’re searching for code, repositories, issues, or users, all the query abilities of github.com are now available via the API as well.

Maybe you want to find popular Tetris implementations written in Assembly. We’ve got you covered. Or perhaps you’re looking for new gems that are using Octokit.rb. No problem. The possibilities are endless.

Highlights

On github.com, we enjoy the context provided by code snippets and highlights in search results.

We want API consumers to have access to that information as well. So, API requests can opt to receive those text fragments in the response. Each fragment is accompanied by numeric offsets identifying the exact location of each matching search term.

Preview period

We’re making this new API available today for developers to preview. We think developers are going to love it, but we want to get your feedback before we declare the Search API “final” and “unchangeable.” We expect the preview period to last for roughly 60 days.

As we discover opportunities to improve this new 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 Search API will become an official component of GitHub API v3. At that point, the new Search API will be stable and suitable for production use.

What about the old search API?

The legacy search API is still available. Many existing clients depend on it, and it is not changing in any way. While the new API offers much more functionality, the legacy search endpoints remain an official part of GitHub API v3.

Take it for a spin

We hope you’ll kick the tires and send us your feedback. Happy searching finding!

When Does My Rate Limit Reset?

Have you ever wondered when your rate limit will reset back to its maximum value? That information is now available in the new X-RateLimit-Reset response header.

$ curl -I https://api.github.com/orgs/octokit

HTTP/1.1 200 OK
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1372700873
...

The X-RateLimit-Reset header provides a Unix UTC timestamp, letting you know the exact time that your fresh new rate limit kicks in.

The reset timestamp is also available as part of the /rate_limit resource.

$ curl https://api.github.com/rate_limit

{
  "rate": {
    "limit": 60,
    "remaining": 42,
    "reset": 1372700873
  }
}

For more information on rate limits, be sure to check out the docs.

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

Feeds API

Today we’re releasing a new Feeds API, an easy way to list all the Atom resources available to the authenticated user.

curl -u defunkt https://api.github.com/feeds

{
  "timeline_url": "https://github.com/timeline",
  "user_url": "https://github.com/{user}",
  "current_user_public_url": "https://github.com/defunkt",
  "current_user_url": "https://github.com/defunkt.private?token=abc123",
  "current_user_actor_url": "https://github.com/defunkt.private.actor?token=abc123",
  "current_user_organization_url": "https://github.com/organizations/{org}/defunkt.private.atom?token=abc123",
  "_links": {
    "timeline": {
      "href": "https://github.com/timeline",
      "type": "application/atom+xml"
    },
    "user": {
      "href": "https://github.com/{user}",
      "type": "application/atom+xml"
    },
    "current_user_public": {
      "href": "https://github.com/defunkt",
      "type": "application/atom+xml"
    },
    "current_user": {
      "href": "https://github.com/defunkt.private?token=abc123",
      "type": "application/atom+xml"
    },
    "current_user_actor": {
      "href": "https://github.com/defunkt.private.actor?token=abc123",
      "type": "application/atom+xml"
    },
    "current_user_organization": {
      "href": "https://github.com/organizations/{org}/defunkt.private.atom?token=abc123",
      "type": "application/atom+xml"
    }
  }
}

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

Repository Statistics

Today we’re happy to open our Repository Statistics API to everyone. We’re using repository statistics to power our graphs, but we can’t wait to see what others can do with this information.

Starting today, these resources are available to you:

• Contributors
• Commit Activity
• Code Frequency
• Participation
• Punch Card

Enjoy!

Create, update, and delete individual files

We’re following in the footsteps of GitHub.com’s ability to edit and create files in your web browser. Starting today, the Repository Contents API will let you easily create, update, and even delete individual files.

Happy editing!

Improved Support for Submodules in the Repository Contents API

When you view a repository with a submodule on github.com, you get useful links and information for the submodule.

Today we’re making that data available in the Repository Contents API.

curl https://api.github.com/repos/jquery/jquery/contents/test/qunit

{
  "name": "qunit",
  "path": "test/qunit",
  "type": "submodule",
  "submodule_git_url": "git://github.com/jquery/qunit.git",
  "sha": "6ca3721222109997540bd6d9ccd396902e0ad2f9",
  "size": 0,
  "url": "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
  "git_url": "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
  "html_url": "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9",
  "_links": {
    "self": "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
    "git": "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
    "html": "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9"
  }
}

If you have any questions or feedback, please drop us a line at support@github.com.

Commit Statuses Now Available for Branches and Tags

Last week we announced support for build statuses in the branches page. Now we are extending this to the API. The API endpoint for commit statuses has been extended to allow branch and tag names, as well as commit SHAs.

curl https://api.github.com/repos/rails/rails/statuses/3-2-stable

Enjoy.

Deprecating a Confusing Attribute in the Pull Request API

When you get the details for a Pull Request from the API, the response provides everything there is to know about that Pull Request. In addition to the useful information provided in the API response, the JSON also includes the merge_commit_sha attribute. This attribute is a frequent source of misunderstanding, and we aim to remove the confusion.

To help current API consumers, we’ve documented the attribute for improved understanding.

To protect future API consumers from this confusion, we have deprecated the merge_commit_sha attribute, and we will remove it in the next major version of the API.

As always, if you have any questions or feedback, please drop us a line at support@github.com.

User Agent now mandatory

After an almost six week grace period, we’re now enforcing the User Agent header for all API requests. Most HTTP libraries (including cURL) set this header by default. If you’re experiencing an increase in 403 responses, be sure and check your code.

If you have any questions or feedback, please drop us a line at support@github.com.

New Hookshot Changes

We are experimenting with changes to the “Hookshot” backend that powers service hooks. There were some significant networking changes with the new cluster, so there are some new IP whitelist rules for hooks:

• 204.232.175.64/27
• 192.30.252.0/22

These are in CIDR notation. They represent a significant range of GitHub addresses, meaning this should be the last IP change for a while. Once this cluster is activated and we shut the other cluster down, we will be removing the other entries.

We are currently testing the new backend with all repositories in the GitHub organization only, and expect to start testing it with user data next week.

This also means we should be able to start accepting GitHub Services pull requests very soon :)

Sortable Stars in Repository Starring API

As we announced on the GitHub blog, Stars now support sorting. The Repository Starring API now supports two new parameters when listing Stars: sort and direction.

curl https://api.github.com/users/defunkt/starred?sort=created&direction=asc

Enjoy.

Hookshot Load balancer

We had an issue with the Hookshot load balancer this morning, causing the majority of hooks to flow to a single node only. This lead to massive queue times. While fixing this, we’re putting the old Services backend in use.

This means the old IPs are back in use. Use this Help guide if you already removed them from your firewall.

Some Hookshot Issues

We turned Hookshot (our new GitHub Services backend) on yesterday. Things have been pretty smooth, with one issue: Hooks going to other EC2 nodes come from the private IP addresses of our nodes in the 10...* range.

If your web hook servers are on EC2 and are missing hooks from GitHub due to an IP restriction, we recommend the following:

1. Remove the IP white list.
2. Fall back to HTTPS and Basic Auth to restrict pushes to authorized senders only.

We’re currently working on solving this problem. Hit up support@github.com if you have any questions.

Upcoming Changes to GitHub Services

We are finishing up a new GitHub Services backend, dubbed “Hookshot”, to increase the speed and reliability of our delivered payloads. We are doing what we can to make this a seamless transition for everyone. However, there are a few notable changes.

• There is a new Meta API endpoint listing the current public IPs that hooks originate from.

• We’re removing the AMQP service from GitHub. It hasn’t worked in quite some time, and the code it uses doesn’t work in our background workers.

• We’re also instituting a new guideline to improve the reliability and maintainability of services in the future. As of today, all new services must accept an unmodified payload over HTTP. Any service that does not will be rejected. To see an example of an acceptable service, check out Code Climate. Notice their service simply accepts HTTP POST from GitHub unmodified. For an example of a service that won’t be accepted after today, check out Campfire. It uses other Ruby gems and contains custom logic to transform the GitHub payload to Campfire messages. Existing hooks will keep working (don’t worry 37signals, we :heart: Campfire).

We’re making these changes because we want to focus on the reliability of the core Services backend for everyone. Maintaining custom logic and libraries for over 100 services is taking too much of this focus away.

User Agent mandatory from March 4th 2013

Following on from our previous post about requiring requests to include a valid User Agent header we will soon be changing our API servers to return HTTP 403 to any clients not providing a valid User Agent header.

We will be making this change on Monday, March 4th 2013.

Setting this helps us identify requests from you, and get in touch with people who are using the API in a way which causes disruption to GitHub. Most HTTP libraries and tools like cURL already provide a valid header for you, and allow you to customize it, so this will not require many of our users to make any changes whatsoever.

If you have any questions or feedback, please drop us a line at support@github.com.

New User scopes

We’ve added a few new user scopes for 3rd party applications that want very specific user functionality. The user:email scope gives apps read-only access to a user’s private email addresses. The user:follow scope lets a user follow and unfollow other users.

This should help keep applications from requiring the user scope, which can be potentially dangerous.

We also added a read-only endpoint to get a user’s public SSH keys.

GET https://api.github.com/users/technoweenie/keys

Diff and patch media types

Starting today, you can get .diff and .patch content directly from the API for the following resources:

• Commits
• Commit comparisons
• Pull request

Simply use the same resource URL and send either application/vnd.github.diff or application/vnd.github.patch in the Accept header:

curl -H "Accept: application/vnd.github.diff" https://api.github.com/repos/pengwynn/dotfiles/commits/aee60a4cd56fb4c6a50e60f17096fc40c0d4d72c

diff --git a/tmux/tmux.conf.symlink b/tmux/tmux.conf.symlink
index 1f599cb..abaf625 100755
--- a/tmux/tmux.conf.symlink
+++ b/tmux/tmux.conf.symlink
@@ -111,6 +111,7 @@ set-option -g base-index 1
 ## enable mouse
 set-option -g mouse-select-pane on
 set-option -g mouse-select-window on
+set-option -g mouse-resize-pane on
 set-window-option -g mode-keys vi
 set-window-option -g mode-mouse on
 # set-window-option -g monitor-activity off

Pagination for Organization Repository lists now paginates properly

Improvements continue to the Organizations Repository listing endpoint. Today we’re improving pagination so that it works as documented. Now you can expect Link headers to navigate through the results space, regardless of what you send in the type parameter.

The docs for Organization Repositories queries are still here:

• Organization Repositories

EDIT: Link headers are our preferred navigation technique.

Finding sources and fork repositories for organizations

We’ve made a couple of changes today to the Organization repositories listing to bring it a bit closer to the functionality of the GitHub.com Organization repositories tab. We now let you retrieve repositories which are forks of another repository, as well as those repositories which are sources (not forks).

# Grab all fork Repositories for an Organization
curl "https://api.github.com/orgs/:org/repos?type=forks"

# Grab all source Repositories for an Organization
curl "https://api.github.com/orgs/:org/repos?type=sources"

Check out the docs for sorting and filtering options:

• Organization Repositories

Create an OAuth authorization for an app

The Authorizations API is an easy way to create an OAuth authorization using Basic Auth. Just POST your desired scopes and optional note and you get a token back:

    curl -u pengwynn -d '{"scopes": ["user", "gist"]}' \
         https://api.github.com/authorizations

This call creates a token for the authenticating user tied to a special “API” OAuth application.

We now support creating tokens for your own OAuth application by passing your twenty character client_id and forty character client_secret as found in the settings page for your OAuth application.

    curl -u pengwynn -d '{ \
                          "scopes": ["user", "gist"], \
                          "client_id": "abcdeabcdeabcdeabcdeabcde" \
                          "client_secret": "abcdeabcdeabcdeabcdeabcdeabcdeabcdeabcdeabcde" \
                         }' \ '
            https://api.github.com/authorizations

No more implementing the web flow just to get a token tied to your app’s rate limit.

Per-repository Review and Issue Comment listing

You’ve always been able to grab all the commit comments for an entire repository via the API, but to get Issue comments and Pull Request Review Comments, you could only fetch the comments for a single Issue or Pull Request.

Today, we’re introducing two new methods to grab all Issue Comments and Review Comments for a repository.

# Grab all Issue Comments
curl https://api.github.com/repos/mathiasbynens/dotfiles/issues/comments

# Grab all Review Comments
curl https://api.github.com/repos/mathiasbynens/dotfiles/pulls/comments

Check out the docs for sorting and filtering options:

• Issue comments
• Review comments

Gitignore Templates API

We recently made it easy to initialize a repository when you create it via the API. One of the options you can pass when creating a repository is gitignore_template. This value is the name of one of the templates from the the public GitHub .gitignore repository.

The Gitignore Templates API makes it easy to list those templates:

curl https://api.github.com/gitignore/templates

HTTP/1.1 200 OK

[
  "Actionscript",
  "Android",
  "AppceleratorTitanium",
  "Autotools",
  "Bancha",
  "C",
  "C++",
  ...

If you’d like to view the source, you can also fetch a single template.

curl -H 'Accept: application/vnd.github.raw' \
     https://api.github.com/gitignore/templates/Objective-C

HTTP/1.1 200 OK

# Xcode
.DS_Store
build/
*.pbxuser
!default.pbxuser
*.mode1v3
!default.mode1v3
*.mode2v3
!default.mode2v3
*.perspectivev3
!default.perspectivev3
*.xcworkspace
!default.xcworkspace
xcuserdata
profile
*.moved-aside
DerivedData
.idea/

Forking to Organizations

We made a slight change to the way you fork a repository. By default, you can fork my repository through an HTTP POST to the repository’s fork resource.

$ curl -X POST https://api.github.com/repos/technoweenie/faraday/forks

This repository forks to your personal account. However, there are cases when you want to fork to one of your organizations instead. The previous method required a ?org query parameter:

$ curl -X POST /repos/technoweenie/faraday/forks?org=mycompany

Query parameters on POST requests are unusual in APIs, and definitely inconsistent with the rest of the GitHub API. You should be able to post a JSON body like every other POST endpoint. Now, you can! Only, now we’re calling the field organization.

$ curl /repos/technoweenie/faraday/forks?org=mycompany \
  -d '{"organization": "mycompany"}'

Don’t worry, we are committed to maintaining the legacy behavior until the next major change of the GitHub API.

Gist comment URIs

The URIs of all gist comments are changing immediately. The new URI pattern for gist comments is /gists/{gist-id}/comments/{id}. (See gist comments section of the docs for more details.) This change is necessary because the auto-incremented ids of gist comments are easy to guess. This predictability allows anyone to view comments on private Gists with relative ease. Obviously, comments on private gists should be just as private as the gist itself.

Adding the gist id to the URI of comments makes it impossible, in practical terms, to guess that URI because the id of private gists are very large random numbers. This is, unfortunately, a breaking change but one that cannot be avoided because of the security implications of the current URIs. We apologize for the inconvenience.

We have also added a comments_url member to the Gist documents. The comments_url link provides access to the comments of a Gist in a way that will insulate clients from changes in the URI patterns used by the GitHub API. We are increasing our use of links in order to make changes such as this one less damaging to clients. We strongly encourage using url and *_url properties, where possible, rather than constructing URIs using the patterns published on this site. Doing so will result in clients that break less often.

Notifications API

Now that the dust has settled around Notifications and Stars, we’ve unleashed all that :sparkles: in a brand new API. You can now view and mark notifications as read.

Endpoint

The core notifications functionality is under the /notifications endpoint. You can look for unread notifications:

$ curl https://api.github.com/notifications

You can filter these notifications to a single Repository:

$ curl https://api.github.com/repos/technoweenie/faraday/notifications

You can mark them as read:

# all notifications
$ curl https://api.github.com/notifications \
    -X PUT -d '{"read": true}'

# notifications for a single repository
$ curl https://api.github.com/repos/technoweenie/faraday/notifications \
    -X PUT -d '{"read": true}'

You can also modify subscriptions for a Repository or a single thread.

# subscription details for the thread (either an Issue or Commit)
$ curl https://api.github.com/notifications/threads/1/subscription

# subscription details for a whole Repository.
$ curl https://api.github.com/repos/technoweenie/faraday/subscription

Polling

The Notifications API is optimized for polling by the last modified time:

# Add authentication to your requests
$ curl -I https://api.github.com/notifications
HTTP/1.1 200 OK
Last-Modified: Thu, 25 Oct 2012 15:16:27 GMT
X-Poll-Interval: 60

# Pass the Last-Modified header exactly
$ curl -I https://api.github.com/notifications
    -H "If-Modified-Since: Thu, 25 Oct 2012 15:16:27 GMT"
HTTP/1.1 304 Not Modified
X-Poll-Interval: 60

You can read about the API details in depth in the Notifications documentation.

Set the default branch for a repository

You can set the default branch for a repository to something other than ‘master’ from the GitHub repository admin screen:

Now, you can update this setting via the API. We’ve added a default_branch parameter to the Edit Repository method:

curl -u pengwynn \
     -d '{"name": "octokit", "default_branch":"development"}' \
     https://api.github.com/repos/pengwynn/octokit

If you provide a branch name that hasn’t been pushed to GitHub, we’ll gracefully fall back to 'master' or the first branch.

Organization Members Resource Changes

Requesting the member list of an organization of which you are not a member now redirects to the public members list. Similarly, requests to membership check resources of an organization of which you are not a member are redirected to the equivalent public membership check. One exception to the latter case is that if you are checking about your own membership the request is not redirected. You are always allowed to know what organizations you belong to.

The changes where made to clarify the purpose of these various resources. The /orgs/:org/members resources are intended for use by members of the organization in question. The /orgs/:org/public_members resources are for acquiring information about the public membership of organizations. If you are not a member you are not allowed to see private membership information so you should be using the public membership resources.

If you have any questions or feedback, please drop us a line at support@github.com.

Rate limit changes for unauthenticated requests

To ensure a high quality of service for all API consumers, we’ve reduced the default rate limit for unauthenticated requests. To enjoy the default rate limit of 5,000 requests per hour, you’ll need to authenticate via Basic Auth or OAuth. Unauthenticated requests will be limited to 60 per hour unless you include your OAuth client and secret.

We’ll soon require all requests to include a valid User Agent header. Setting a unique value for this header helps us identify requests and get in touch with developers who are abusing the API. Most HTTP libraries, wrapper libraries, and even cURL provide a valid header for you already and allow you to change it to something unique to your application.

If you have any questions or feedback, please drop us a line at support@github.com.

Initialize a repository when creating

Today we’ve made it easier to add commits to a repository via the GitHub API. Until now, you could create a repository, but you would need to initialize it locally via your Git client before adding any commits via the API.

Now you can optionally init a repository when it’s created by sending true for the auto_init parameter:

curl -i -u pengwynn \
     -d '{"name": "create-repo-test", "auto_init": true}' \
     https://api.github.com/user/repos

The resulting repository will have a README stub and an initial commit.

.gitignore templates

Along with this change, you can set up your .gitignore template by passing the basename of any template in the GitHub gitignore templates project.

curl -i -u pengwynn \
     -d '{"name": "create-repo-test", "auto_init": true, \
          "gitignore_template": "Haskell"}' \
     https://api.github.com/user/repos

As the docs point out, the gitignore_template parameter is ignored if auto_init is not present and true.

If you have any questions or feedback, drop us a line at https://github.com/contact, support@github.com, or @GitHubAPI.

Upcoming Changes to Watcher and Star APIs

We recently changed the Watcher behavior on GitHub. What used to be known as “Watching” is now “Starring”. Starring is basically a way to bookmark interesting repositories. Watching is a way to indicate that you want to receive email or web notifications on a Repository.

This works well on GitHub.com, but poses a problem for the GitHub API. How do we change this in a way that developers can gracefully upgrade their applications? We’re currently looking at rolling out the changes in three phases over an extended period of time.

Current Status

The current Repository Starring methods look like this:

• /repos/:owner/:repo/watchers - A list of users starring the repository.
• /users/:user/watched - A list of repositories that a user has starred.
• /user/watched - A list of repositories the current user has starred.

Phase 1: Add Watchers as Subscriptions

This phase exposes Watchers as “Subscriptions”. This is to keep from clashing with the legacy endpoints. This phase will happen automatically and will not break your application until Phase 3 starts. (UPDATE: API v3 will continue to support this functionality indefinitely.)

• /repos/:owner/:repo/subscribers - A list of users watching the repository.
• /users/:user/subscriptions - A list of repositories that a user is watching.
• /user/subscriptions - A list of repositories the current user is watching.

We’ll also add a copy of the legacy Watchers API in the new endpoint:

• /repos/:owner/:repo/stargazers - A list of users starring the repository.
• /users/:user/starred - A list of repositories that a user has starred.
• /user/starred - A list of repositories the current user has starred.

This is in place now with the current media type for the API:

application/vnd.github.beta+json

If you care about your application not breaking, make sure all outgoing API requests pass that value for the “Accept” header. You should do this now. This can be verified by checking the X-GitHub-Media-Type header on all API responses.

# Accesses a user's starred repositories.
curl https://api.github.com/user/watched \
  -H "Accept: application/vnd.github.beta+json"

-This Phase will be broken once Phase 3 starts. Phase 3 removes all support for the "beta" media type, and makes the "v3" media type the implicit default for API requests.

UPDATE - November 6, 2013

Phase 2: Switch /watchers API Endpoint

application/vnd.github.v3+json

# Accesses a user's watched repositories.
curl https://api.github.com/user/watched \
  -H "Accept: application/vnd.github.v3+json"

Phase 3: Remove /subscribers API Endpoint.

We look forward to assisting you through this transition. Hit us up at https://github.com/contact, support@github.com, or @GitHubAPI.