Creating a repository dispatch event now official part of GitHub API

The "Creating a repository dispatch event" endpoint no longer requires the everest preview.

 application/vnd.github.everest-preview+json

For more information about this endpoint, see the "Create a repository dispatch event."

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

Moving the teams API

We are announcing a new set of endpoints in the Teams API. The new endpoints will allow us to scale and support the Teams API long-term.

The Team APIs will be moving from a top-level path under /teams/:team_id to a scoped path under the organization that owns the team with a path like /organizations/:org_id/team/:team_id. In this move we also are adding support to making these APIs available under a named path as well with /orgs/:org/teams/:team_slug.

Deprecation timeline

The existing API endpoints will be disabled a year from now at the earliest on February 1st 2021.

What changes to make

If you're already using an API endpoint under /teams/:team_id, the easiest way to update your code is to switch to the /organizations/:org_id/team/:team_id endpoint. If you're unsure what org_id to use, you can find it by retrieving the current team under /teams/:team_id. You'll find the org_id inside the organization hash as the id field in the response.

Note: The endpoint routes using organization and team id use the singular team. The plural form of the route already exists. For example, /organizations/:org_id/teams/:team_slug.

Endpoints affected

These endpoints are being deprecated:

These are the new replacement team API endpoints:

As mentioned, these new replacement team API endpoints are available both as /orgs/:org/teams/:team_slug for name based access, and as /organizations/:org_id/team/:team_id for id based access.

If you have any questions or feedback, please let us know!

Revoke GitHub Apps installation tokens with the REST API

Now you can revoke GitHub App installation tokens using the REST API.

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

application/vnd.github.gambit-preview+json

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

For more information, see the "Revoke an installation access token" endpoint.

The Source Import API ends preview

The Source Import API is now an official part of the GitHub API.

To use the Source Import API, you no longer need the barred-rock preview.

application/vnd.github.barred-rock-preview

For more information about this API, see "Source Imports API."

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

Several API previews graduate

There are several features that are now officially part of the GitHub REST API v3.

To use the affected API endpoints, you no longer need to pass preview headers. Before these previews graduated, you had to include preview headers as a custom media type in the Accept header to use these endpoints.

Graduated previews

  • To transfer a repository, you no longer need the Nightshade preview.

    application/vnd.github.nightshade-preview+json

  • To invite users to an organization, you no longer need to use the Dazzler preview.

    application/vnd.github.dazzler-preview+json

  • To access the Team Discussions API, you no longer need the Echo preview.

    application/vnd.github.echo-preview+json

  • To use emoji in label names, add descriptions to labels or search for labels in a repository, you no longer need to use the Symmetra preview.

    application/vnd.github.symmetra-preview+json

  • To retrieve someone's hovercard information in different contexts using the Hovercard API, you no longer need the Hagar preview.

    application/vnd.github.hagar-preview+json

  • To see nested teams in your responses or use the Nested Teams API, you no longer need the Hellcat preview.

    application/vnd.github.hellcat-preview+json

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

API changes to support internal repository visibility

Customers with an enterprise account using GitHub Enterprise Cloud and GitHub Enterprise Server 2.20+ have access to a third visibility option beyond public and private, called internal. We've made some recent API changes to support this option.

Repository Creation Policy

The REST v3 and GraphQL v4 APIs now support setting and retrieving granular repository creation permissions.

REST v3 API

In the REST v3 API, Get an organization and Update an organization endpoints have three new fields added to the existing surtur preview:

  • members_can_create_public_repositories
  • members_can_create_private_repositories
  • members_can_create_internal_repositories

In Get an organization and Update an organization, the existing members_allowed_repository_creation_type field remains for backward compatibility but is deprecated and will be removed in the future. Its return value ignores internal repositories.

Values provided in the new fields while editing an organization override the existing members_allowed_repository_creation_type field.

GraphL v4 API

Similar changes apply to the GraphQL v4 API. The EnterpriseOwnerInfo object has three new fields indicating the policy setting for Enterprise accounts:

  • membersCanCreatePublicRepositoriesSetting
  • membersCanCreatePrivateRepositoriesSetting
  • membersCanCreateInternalRepositoriesSetting

These new fields coexist with the old membersCanCreateRepositoriesSetting which does not account for internal repository creation policy. This field is now deprecated and will be removed in the future.

The UpdateEnterpriseMembersCanCreateRepositoriesSetting mutation includes four new input fields:

  • membersCanCreateRepositoriesPolicyEnabled, which toggles enterprise policy enforcement over organizations.
  • membersCanCreatePublicRepositories
  • membersCanCreatePrivateRepositories
  • membersCanCreateInternalRepositories

These new fields coexist with the old settingValue which does not account for internal repository creation policy. This field is also deprecated and will be removed in the future.

Repository Visibility Fields

You can now set and retrieve the visibility of a repository with a new field that accommodates internal repositories, which are available to enterprise accounts using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+. In the REST v3 API, you will see the following changes:

These endpoints show visibility key in the response:

These endpoints have new input parameters:

To access the visibility field for any of these endpoints, you must provide a custom media type in the Accept header:

application/vnd.github.nebula-preview+json

If you have any questions or feedback, please let us know.

Introducing the "Managing enterprise accounts" GraphQL API

Now you can manage your enterprise account using the GraphQL API, which efficiently returns just the data you request. This API is designed to handle all of your enterprise account management needs, from monitoring account settings, access changes, and users within your enterprise. The Managing Enterprise Accounts API is available for GitHub Enterprise Cloud and for GitHub Enterprise Server.

For more information, see "Managing enterprise accounts."

Deprecated APIs and authentication

We are announcing deprecations that will improve the security of GitHub apps and APIs, but we haven't removed anything yet. We hope that communicating this information early will help you plan for the authentication and authorization changes you will need to make.

Deprecation timeline

We will provide more information during the following few months, including the exact timeline for discontinuing the support of these deprecations. While we are not removing anything right now, we will follow up with a blog post that outlines the changes and the timeline in which we will no longer support the following deprecated endpoints and authentication methods.

Authenticating using passwords

GitHub is deprecating password authentication to the API. Instead of using password authentication, create a personal access token using your Personal access tokens settings page in limited situations like testing. You should authenticate apps in production by using the web applications flow. For more information, see "Authorizing OAuth Apps."

Authenticating using query parameters

GitHub is deprecating authentication to the GitHub API using query parameters, such as using a access_token query parameter for OAuth user authentication or a client_id/client_secret query parameter for OAuth application authentication. All authentication to the GitHub API should be done using HTTP basic authentication.

Authenticating with SAML organizations

Apps must use the web application flow to obtain OAuth tokens that work with GitHub SAML organizations. OAuth tokens created using the Authorizations API are unable to access resources for GitHub SAML organizations.

Deprecating and adding endpoints for the OAuth Authorizations and OAuth Applications APIs

GitHub is deprecating the Authorizations API, which includes these endpoints:

Some client-side integrations use the deprecated Authorizations API to create personal access tokens and OAuth access tokens. These tokens must now be created using our web application flow. When appropriate, personal access tokens can still be created by the user on the Personal access tokens page. However, most integrations should register themselves as an OAuth application and use the web application flow to obtain an OAuth access token.

GitHub has replaced several deprecated endpoints with new ones. You can now find both the deprecated and new endpoints in the OAuth Applications API. Specifically, we have deprecated OAuth Applications API endpoints containing an OAuth token as a path parameter:

These new endpoints replace the deprecated endpoints:

Updating command-line utilities to use localhost-based redirect URLs

Command-line tools now support a web-based flow by using localhost-based redirect URLs and specifying a port. We have extended our support for localhost-based redirect URLs to securely improve the experience of command-line utilities for client-side integrations. Historically these tools have relied on the Authorizations API, and they have not been able to easily register an OAuth URL callback to use with our OAuth web application flow. Please see our documentation on redirect URLs for more information.

If you have any questions or feedback, please let us know!

List GitHub App installations for an organization

Now as an organization owner, you can list all GitHub App installations for an organization using the REST API. You must be an organization owner with admin:read scope to use this endpoint. The installation count includes all GitHub Apps installed on repositories in the organization.

GET /orgs/:org/installations

To list all GitHub App installations for an organization, you must provide the machine-man custom media type in the Accept header:

application/vnd.github.machine-man-preview+json

During the preview period, we may change aspects of these APIs based on developer feedback.

If we do, we will announce the changes here on the developer blog, but we will not provide any advance notice. If you have any questions or feedback, let us know.

GitHub Pages features become an official part of the REST API

The features that are a part of the GitHub Pages mister-fantastic-preview are now available on GitHub.com and will be available in the next versions of GitHub Enterprise (2.19 and higher). You will no longer need to pass a preview header to use most GitHub Pages API endpoints.

Preview media type no longer needed

Now that the preview period has ended (first announced in July 2016), you no longer need to pass the mister-fantastic-preview custom media type. Instead, we recommend that you specify v3 as the version in the Accept header:

application/vnd.github.v3+json

Please note that if you use GitHub Enterprise versions 2.8 to 2.18, you will still need to provide this custom media type in the Accept header:

application/vnd.github.mister-fantastic-preview+json

Onward! Thanks again to everyone that tried out these GitHub Pages API features during the preview period.

Recent Posts

Subscribe to the RSS feed