Ensure your app is ready for Protected Branches

We’ve begun to roll out Protected Branches across GitHub. When you protect a branch in one of your repositories, you will be prevented from force pushing to that branch or deleting it. You can also configure required status checks for your protected branch. When configured, changing a branch to point at a new commit will fail unless that commit (or another commit with the same Git tree) has a Status in the success state for each required status check.

These restrictions apply to branch manipulations performed via the GitHub API as well. So when you protect a branch, you will no longer be able to delete the branch via the API or update it to point at a non-ancestor commit, even with "force": true. And if your branch has required status checks, you won’t be able to update it or merge pull requests into that branch until success Statuses have been posted to the target commit for all required status checks.

These restrictions are all represented by 422 errors:

curl -i -H 'Authorization: token TOKEN' \
   -X DELETE https://api.github.com/repos/octocat/hubot/git/refs/heads/master
HTTP/1.1 422 Unprocessable Entity
{
 "message": "Cannot delete a protected branch",
 "documentation_url": "https://help.github.com/articles/about-protected-branches"
}

Protected branches and required status checks are a great way to ensure your project’s conventions are followed. For example, you could write a Status integration that only posts a success Status when the pull request’s author has signed your project’s Contributor License Agreement. Or you could write one that only posts a success Status when three or more members of your @initech/senior-engineers team have left a comment saying they’ve reviewed the changes. If you configure these integrations as required status checks, you can be sure that these conditions have been satisfied before a pull request is merged. See our Status API guide to learn how to create integrations like these.

If you have any questions, please let us know.

Get the contents of a repository’s license

The License API Preview now allows you to retrieve the contents of a repository's open source license. As before, when the appropriate preview media type is passed, the repository endpoint will return information about the detected license, if any:

curl -H "Accept: application/vnd.github.drax-preview+json" https://api.github.com/repos/benbalter/gman

You can now also get the contents of the repository's license file, whether or not the license was successfully identified via the license contents endpoint:

curl -H "Accept: application/vnd.github.drax-preview+json" https://api.github.com/repos/benbalter/gman/license

Similar to the repository contents API, the license contents method also supports custom media types for retrieving the raw license content or rendered license HTML.

curl -H "Accept: application/vnd.github.drax-preview.raw" https://api.github.com/repos/benbalter/gman/license

For more information, see the license API documentation, and as always, if you have any questions or feedback, please get in touch with us.

More flexible options for listing repositories

The List your repositories API now offers additional parameters to help you fetch the exact set of repositories you're looking for:

• The visibility parameter lets you request only your public repositories, only your private repositories, or both.
• With the affiliation parameter, you can ask for repositories you own, repositories where you are a collaborator, repositories you have access to as an organization member, or any combination that suits your needs.

Use these new parameters separately, together, or in combination with other parameters to craft flexible queries that fetch the specific repositories you're seeking.

For full details, check out the documentation. If you have any questions, please get in touch!

Automatic redirects for renamed repositories

To help API clients gracefully handle renamed repositories, the API now automatically redirects to the repository’s new location.

Our thanks goes out to everyone that tried out this enhancement during the preview period. During the preview period, you needed to provide a custom media type in the Accept header to opt-in to the redirects. Now that the preview period has ended, you no longer need to specify this custom media type.

To learn more about these redirects and how they benefit your applications, be sure to check out the preview period announcement. As always, if you have any questions, we're here to help.

API enhancements for working with organization permissions

We're introducing several enhancements to allow API developers to take advantage of the improved organization permissions that we are rolling out. Learn about these enhancements and how you can try them out below.

Since we're rolling out the improved organization permissions improvements slowly, these enhancements will only apply to certain organizations at first. Most of these enhancements will degrade gracefully (returning an empty array or something similar) if used on an organization that doesn't support improved organization permissions yet. Check the documentation for your specific API to see if errors are possible.

API enhancements

Team permissions

In our improved permissions system, a team no longer has a single permission that applies to all of its repositories. Instead, each repository is added to a team with its own permission. For example, an organization could use a single team to grant pull access to one repository, push access to a second, and admin access to a third.

The team APIs now support this more granular notion of permissions:

• The Add team repository API accepts a permission parameter, so that you can specify whether a team should grant pull, push, or admin access on a given repository.
• In the List team repositories and Check if a team manages a repository API, the response includes a permissions attribute, indicating whether the team grants pull, push, or admin access on each repository.
• The permission parameter in the Create team and Edit team APIs is deprecated. Since teams can grant a different permission on each repository, this parameter no longer dictates what permission a team grants on all of its repositories. Instead, it dictates the default permission that the Add team repository API will use for requests where no permission parameter is specified.

Team privacy

We now allow you to modify the privacy level of your teams. A "secret" team can only be seen by organization owners and people who are members of that team (which is how all teams have worked historically), while a "closed" team is visible to every member of the organization (which makes it easier to use @mentions throughout your organization).

The team APIs now support this new team privacy concept:

• The Create team and Edit team APIs accept a privacy parameter, so that you can specify whether a team should be secret or closed.
• All team resources in the API now include a privacy attribute, indicating whether the team is secret or closed.

Team maintainers

We've added the ability for you to delegate team maintenance to non-owners, reducing the workload for your organization's owners. You can now promote a non-owner member of a team to be a "maintainer" of that team. A maintainer can add and remove team members and change the team's title and description.

The team membership APIs now support this new team maintainer concept:

• The Add team membership API accepts a role parameter, so that you can specify whether a given team member should be a maintainer or a regular member.
• The List team members API accepts an optional role parameter, allowing you to fetch only maintainers or only regular members.
• In the Get team membership and Add team membership APIs, the response includes a role attribute, indicating whether a user is a maintainer or a regular member of the team.

Filtering organization members by role

The organization Members list API now accepts a role parameter, so that you can request to see only the owners (or non-owners) of your organization.

Repository collaborators

We now allow you to add collaborators directly to organization-owned repositories, just like we always have for user-owned repositories.

The collaborator APIs now support organization-owned repositories:

• The Add user as a collaborator API works for organization-owned repositories. We've also added a permission parameter to it (currently valid for organization-owned repositories only), so that you can specify what level of access the collaborator should have on the repository.
• In the List collaborators API, the response includes a permissions attribute describing the permissions that each collaborator has on your organization's repositories.

Preview period

Starting today, these API enhancements are available for developers to preview. At the end of the preview period, these enhancements will become official components of the GitHub API.

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

application/vnd.github.ironman-preview+json

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

Send us your feedback

We would love to hear your thoughts on these enhancements. If you have any questions or feedback, please get in touch with us!

Breaking changes to organization permissions are now official

As promised earlier this month, the API changes related to managing organization members and repositories are now official parts of the GitHub API.

During the migration period, you needed to provide a custom media type in the Accept header to opt-in to the changes. Now that the migration period has ended, you no longer need to specify this custom media type.

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

Licenses API update

We are expanding the Licenses API to make it more useful for auditing license usage across all repositories owned by a user or organization.

Before, license information was only returned for an individual repository:

GET /repos/github/hubot

Now, license information will also be included in responses from endpoints that list multiple repositories, such as List organization repositories:

GET /orgs/github/repos

As before, 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

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

List all organizations

We've added a new API method to list all organizations:

curl https://api.github.com/organizations
[
  {
    "login": "github",
    "id": 9919,
    "url": "https://api.github.com/orgs/github",
   "repos_url": "https://api.github.com/orgs/github/repos",
   "events_url": "https://api.github.com/orgs/github/events",
   "members_url": "https://api.github.com/orgs/github/members{/member}",
   "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
   "avatar_url": "https://avatars.githubusercontent.com/u/9919?v=3",
    "description": "GitHub, the company."
  },
  ...
]

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

GitHub Pages' A Records Added to Meta API

The Meta API now includes the A record IP addresses for GitHub Pages.

curl https://api.github.com/meta

{
  "verifiable_password_authentication": true,
  "github_services_sha": "23c6105183b626cf74c045f6d53af7a178bfdb4c",
  "hooks": [
    "192.30.252.0/22"
  ],
  "git": [
    "192.30.252.0/22"
  ],
  "pages": [
    "192.30.252.153/32",
    "192.30.252.154/32"
  ]
}

These IP addresses are used to configure A records with your DNS provider for GitHub Pages. These addresses have changed a few times in the past. This API always provides the current addresses so that you can automate the process of keeping your DNS records up to date.

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

Breaking changes to organization permissions coming on June 24

Back in January, we encouraged developers to update their applications to prepare for upcoming API changes related to managing organization members and repositories. In order to support the upcoming improvements to organization permissions, these changes will become official parts of GitHub API v3 on June 24.

If your application relies on any of the affected functionality (described below), be sure to update your code before June 24 to account for these changes.

Breaking changes coming on June 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][list-your-organizations] API
• The [List user organizations][list-user-organizations] API

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

In January, we announced a migration period allowing API consumers to opt in to these changes. If you haven't already opted in to these changes, you still do so as described below. On June 24, these changes will become official parts of GitHub API v3. At that time, these changes will apply to all API consumers.

Migration period

During these final days of 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][contact]!

[list-user-organizations]: /v3/orgs/#list-organizations-for-a-user[list-your-organizations]: /v3/orgs/#list-organizations-for-the-authenticated-user[contact]: https://github.com/contact?form[subject]=Organization+Permissions+API