GitHub API Changes

Licenses API

2015-03-09T00:00:00Z

We’re introducing a new license API preview to support open source license usage on GitHub.com.

To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.drax-preview+json

This will then expose two new API endpoints. You can get a list of all known licenses:

GET /licenses

Or get information about a particular license:

GET /licenses/mit

When the preview media type is passed, the repository api will also return information about a repository’s license file when you get an individual repository:

GET /repos/github/hubot

For more information, see the licenses API documentation, and if you have any questions or feedback, please let us know.

More time to prepare for the breaking changes to organization permissions

2015-02-24T00:00:00Z

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

2015-02-19T00:00:00Z

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

2015-02-18T00:00:00Z

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)

2015-02-03T00:00:00Z

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

2015-01-19T00:00:00Z

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.

New guide: Discovering resources for a user

2015-01-08T00:00:00Z

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

2015-01-07T00:00:00Z

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

Replace older SSH keys created by your application

2014-12-12T00:00:00Z

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.

New Attributes for Starring API

2014-12-09T00:00:00Z

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

2014-12-08T00:00:00Z

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

2014-12-08T00:00:00Z

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

2014-12-03T00:00:00Z

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

2014-11-25T00:00:00Z

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

2014-10-29T00:00:00Z

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

2014-10-21T00:00:00Z

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

2014-10-16T00:00:00Z

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

2014-10-06T00:00:00Z

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

2014-09-23T00:00:00Z

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 “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

2014-09-16T00:00:00Z

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

2014-09-12T00:00:00Z

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

2014-09-05T00:00:00Z

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

2014-08-28T00:00:00Z

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

2014-08-15T00:00:00Z

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

2014-08-05T00:00:00Z

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

2014-07-28T00:00:00Z

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

2014-07-09T00:00:00Z

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

2014-07-07T00:00:00Z

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!

2014-06-23T00:00:00Z

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

2014-06-19T00:00:00Z

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.

GitHub API Changes

Licenses API

More time to prepare for the breaking changes to organization permissions

Breaking changes to Authorizations API responses on April 20

Breaking changes coming on April 20

Migration period

New Releases API methods

Removing token attribute from Authorizations API responses (Update)

Extended preview period

An integrator's guide to organization application policies

Guiding principles

Checking organization access

Listing accessible organization resources

Ensuring uninterrupted SSH access

We’re here to help

New guide: Discovering resources for a user

Prepare for upcoming organization permissions changes

Breaking changes coming on February 24

Migration period

Replace older SSH keys created by your application

How should you replace these keys?

1. Identify the affected keys

2. Inform the affected users

3. Add a new key

4. Delete the old key

We’re here to help

New Attributes for Starring API

Feedback

Preview the upcoming organization permission changes

What’s happening to the Owners team?

What should you do?

Adding an organization admin

Removing an organization admin

Listing organization admins

Checking if someone is an organization admin

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

What should you do?

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

What should you do?

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

What should you do?

Preview period

Migration period

Removing token attribute from Authorizations API responses

What’s changing?

Who is affected?

What should you do?

Preview period

Migration period

Why SHA-256 over bcrypt?

Preview the New Organization Webhooks API

The Deployments API is official

Preview media type no longer needed

Feedback

Status API Limits

Deployment webhook payload changes

DeploymentEvent Changes

Old Format

Current Format - 2014/10/22

New Format - 2014/11/05

DeploymentStatusEvent Changes

Old Format

Current Format - 2014/10/22

New Format - 2014/11/05

Removed SSLv3 support from webhooks and services

New Attributes for Issue Events API

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

The Organization and Team Membership APIs are now official

Finalizing the Organization and Team Membership APIs

Preview period ends on September 23

Reminder: Breaking change to legacy endpoint

Addition to the Organization Membership API

Changing organization feeds in the Feeds API

Changes to the deprecated attributes

New attribute for organization feeds

Removing Gravatar ID from user payloads

Accepting organization invitations from the API

The new Organization Memberships API

New Team Membership API response attribute

Preview period