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 Edit 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 Edit 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:

  • Create repository has a new visibility field which can be public, private, or internal. A value provided here overrides any value set in the existing private field.
  • Edit repository also has a new visibility field with the same behavior as the Create endpoint.
  • List organization repositories has a new internal input option for the type parameter.

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. We will provide more information during the following few months, including the exact timeline for discontinuing the support of these deprecations.

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.

Multi-line comments

Now you can create comments across multiple lines of code in a pull request diff using REST API or GraphQL.

To create multi-line comments or see multi-line comments with the new supported fields when you fetch comment responses, you must provide a custom media type in the Accept header:

application/vnd.github.comfort-fade-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, please let us know.

Team sychronization become an official part of REST API

The features that are a part of the team sychronization team-sync-preview are now available on GitHub.com. Going forward, the Team synchronization API endpoints will be available without a preview header.

Preview media type no longer needed

Now that the preview period has ended (first announced in June 2019), you no longer need to pass the team-sync-preview custom media type.

More check annotations are now shown on the "Files changed" tab

In May of 2018, we announced the Checks API, which added many new capabilities for running checks on code. One of those new capabilities were check annotations, which let apps annotate specific lines of code as part of a check run.

demo-screenshot-of-unchanged-files-with-check-annotations

Check annotations point directly to those lines where a test failure or a lint error occurred, and they empower users to fix any kind of errors or warnings quickly so they can move forward with their pull requests.

demo-screenshot-from-checks-api-blog-post

Today we're making check annotations even more powerful by bringing more of them to where you're already looking: the "Files changed" tab. Checks annotations created on lines or files that were not modified as part of a pull request will now be prominently displayed alongside the diff.

Internal testing has proven that surfacing unchanged files with check annotations has been especially beneficial to our workflows, because test failures can often happen on files that weren't modified as part of a pull request.

Click here to see it in action!

The best part? The API for creating check annotations has not changed. If you're already creating annotations on files or lines outside of the diff, then there's no need to modify any code to use this improvement.

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

Grant GitHub Apps push access to protected branches

The Protected Branches API now allows you to grant GitHub Apps push access to protected branches.

You can only grant GitHub Apps push access to a protected branch if they have been installed with the repository contents write permission.

The Protected Branches API now includes the following endpoints:

The existing endpoint to set branch protection now accepts app restrictions:

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