Changes to the Checks REST API

The following changes are being introduced to the Checks REST API and will take permanent effect on August 27th, 2018.

filename is being renamed to path

Previously, constructing an annotation required you to provide a filename value. However, more accurately, this argument is a path relative to the repository's root directory. As such, the argument you need to provide is being renamed to path.

We will continue to accept the filename argument for one week, after which, path will be required. Responses will also change to provide the path value.

blob_href is no longer necessary

Previously, constructing an annotation required you to also provide a blob_href value. This argument is no longer necessary. Responses will continue to provide the blob_href value.

warning_level is being renamed to annotation_level

Previously, constructing an annotation required you to provide a warning_level value. However, this argument name is not accurate, because an annotation can also be marked as another type, such as a failure or info. As such, the argument to provide is being renamed to annotation_level.

We will continue to accept the warning_level argument for one week, after which, annotation_level will be required. Responses will also change to provide the annotation_level value.

POST /repos/:owner/:repo/check-suite-requests is being removed

This endpoint allows you to create a check suite, or rerequest every single check suite that exists on a repository.

We're removing this endpoint because, from our observations on its usage, it's not useful to be able to trigger the creation of check suites for every App on the repository.

POST /repos/:owner/:repo/check-suites/:check_suite_id/rerequest is being added

As a replacement for the above, we have provided an endpoint to only allow for the rerequesting of a single check suite. This endpoint will trigger the check_run webhook event with the action rerequested. When a check suite is rerequested, its status is reset to queued and the conclusion is cleared.

Share your feedback

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!

Renaming and deprecation of GitHub App Installation Access Token route

In order to Authenticate as an installation, you need to create an installation access token for your GitHub App.

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github.machine-man-preview+json" \
https://api.github.com/installations/:installation_id/access_tokens

On September 4th we will be removing this route along with the GitHub Apps preview period.

You will need to update your API calls to use the following:

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github.machine-man-preview+json" \
https://api.github.com/app/installations/:installation_id/access_tokens

These routes are functionally identical, so there's no need to make any further changes!

Note: This update only affects users of GitHub.com and future versions of GitHub Enterprise.

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

Preview the GraphQL API for Checks Mutations

As part of our ongoing work to create a GraphQL API for Checks, you can now run mutations for creating or updating check suites and check runs!

Similar to the REST endpoints, this API is under a preview period. To access this new API during the preview period, you must provide a custom [media type][media-type] in the Accept header:

application/vnd.github.antiope-preview

Note: GraphQL APIs under preview cannot be accessed via the GraphQL Explorer at this time.

Support for column information

Ever wished you could provide character-specific information using check runs? Now you can!

For both the GraphQL API and the REST API, check annotations can include a column argument to provide starting and ending column information. Check out the documentation for more information.

New webhook event for GitHub Apps using User-to-Server tokens

If your GitHub App identifies or authorizes users, those users have the option to revoke the GitHub App authorization from their settings page.

Previously, your GitHub App had no way of knowing when this occurred and may have continued to make User-to-Server requests with the now revoked access token, leading to a 401 Bad Credentials error.

Today, we're introducing the github_app_authorization webhook event, which will be delivered to your GitHub App whenever a user revokes their authorization. The event action is revoked as you can see in the example webhook payload below:

{
  "action": "revoked",
  "sender": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjIxMDMxMDY3",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  }
}

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

Preview the GraphQL API for Checks

As part of our ongoing work to create a GraphQL API for Checks, you can now query for check runs, suites, and annotation information!

Similar to the REST endpoint, this API is under a preview period. To access this new API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.antiope-preview

Note: GraphQL APIs under preview cannot be accessed via the GraphQL Explorer at this time.

Changes to the Checks REST API

As part of this change, we are also changing the response provided by the REST API in the CheckSuiteEvent.

Previously, when querying a check suite, the REST API would return a key named unique_check_runs_count to indicate the quantity of check runs that had run as part of the latest push. Now, this key is called latest_check_runs_count to better indicate which types of check runs are being counted.

For one week, we will make both keys available in the response; on July 18, 2018, we will remove unique_check_runs_count and only provide latest_check_runs_count.

Share your feedback

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!

New API parameters for project card archiving

We're adding some API parameters to support the new project card archiving feature.

Archiving and restoring a project's cards

To archive a card, use the Update a project card API endpoint, passing true for the archived parameter. To restore an archived card, use the same API endpoint, passing false for the archived parameter.

Viewing a column's archived cards

When using the List project cards API endpoint, you can now specify whether or not you'd like to see a column's archived cards. By default, you will only see cards in the column that are not archived, but if you pass "archived" for the archived_state parameter, you will see that column's archived cards instead. If you pass "all" for the archived_state parameter, you will see every card in the column, whether or not it is archived.

Preview period

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

application/vnd.github.inertia-preview+json

During the preview period, we may change aspects of these API parameters 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!

New endpoints to find app installations

We've released new endpoints to help you find installations of your app for a given organization, repository, or user.

When authenticated as a GitHub App, you can now use the following endpoints:

How can I try it?

To access this functionality, you’ll need to provide the following custom media type in the Accept header:

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

If you have any questions or feedback, please let us know on the platform forum.

Global node IDs become an official part of REST API v3

The node_id attribute, used to identify objects in our GraphQL API from our REST API, has just graduated from preview for GitHub dotcom and GitHub Enterprise versions 2.14 and higher. The node_id attribute will be included in all supported REST resources that have a corresponding GraphQL object, and you can use this information to help move between the REST API and the GraphQL API. For more information, see "Migrating from REST to GraphQL" and "Using global node IDs."

Preview media type no longer needed

Now that the preview period has ended (first announced in December 2017), 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

Please note that if you use GitHub Enterprise versions 2.11 to 2.13, you will still need to provide a custom media type in the Accept header:

application/vnd.github.jean-grey-preview+json

Onward! Thanks again to everyone that tried out GraphQL global node IDs during the preview period. If you have any questions or feedback, please let us know on the GitHub Platform Forum.

User Migration API public beta

Starting today, both users and organizations now have the ability to request an archive of their repositories, issues, comments, and other data using the Migrations API.

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

application/vnd.github.wyandotte-preview+json

During the preview period, we may change aspects of these API methods based on your feedback. If we do, we'll announce the changes here on the developer blog, but we won't provide advance notice.

Requesting a user migration archive

Before you can download an archive of your data, you must first export it. To start a migration, make a POST request to the /user/migrations endpoint, listing the repositories you'd like to include in the archive:

curl -X POST -H "Accept: application/vnd.github.wyandotte-preview+json" -u USERNAME:TOKEN --data '{"repositories":["USERNAME/REPO", "USERNAME/ANOTHER_REPO"]}' https://api.github.com/user/migrations

Checking the status of a migration

After you've started a migration, you can check the status of your archive by making a GET request to the /user/migrations/:migration_id endpoint, using the migration ID provided in the response to your initial request (or as retrieved from GET /user/migrations):

curl -X GET -H "Accept: application/vnd.github.wyandotte-preview+json" -u USERNAME:TOKEN https://api.github.com/user/migrations/:migration_id

Retrieving the archive URL

Once your migration is in the exported state, you can request the URL to your migration archive by making a GET request to the /user/migrations/:migration_id/archive endpoint. This endpoint will return an authenticated URL which you can use to retrieve your archive as a tar.gz file:

curl -X GET -H "Accept: application/vnd.github.wyandotte-preview+json" -u USERNAME:TOKEN https://api.github.com/user/migrations/:migration_id/archive

Deleting an archive

Your migration archive will remain available to download for seven days. If you would like to delete your archive sooner, you can do so by making a DELETE request to the /user/migrations/:migration_id/archive endpoint:

curl -X DELETE -H "Accept: application/vnd.github.wyandotte-preview+json" -u USERNAME:TOKEN https://api.github.com/user/migrations/:migration_id/archive

While the migration will continue to exist, the exported archive and its contents will not.

Exporting all user-owned repositories

[Updated 07-05-18] If you'd like to export all your repositories and have Ruby installed, you can use the following code to conveniently generate a list of repository names to supply in the body of the POST /user/migrations request:

gem install octokit
OCTOKIT_ACCESS_TOKEN=TOKEN ruby -e "require 'octokit'; puts Octokit::Client.new(auto_paginate: true).repos(nil, type: :owner).map(&:full_name).to_json"

If you'd prefer to make the necessary API request(s) yourself, you can retrieve a list of your repositories by making a GET request to the /user/repos endpoint:

curl -u USERNAME:TOKEN https://api.github.com/user/repos?type=owner&per_page=100

Please note, however, that if you have more than 100 repositories, you'll need to follow the instructions for paginating requests.

We hope these endpoints can help users to back up or archive their repository data and better understand what information GitHub stores on their behalf.

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

Request further actions from a check run

Building on the recent Checks API, we're providing further actions that users can request from a check run. This feature enables users to select an action offered by the app. For example, users can push a button in GitHub to request that the app fixes previously found linter errors.

Workflow

  1. The integrator indicates that they can apply a further action. We designed these actions to be flexible for the integrator to specify which actions they can offer the user.

    For example, a linter type app with the ability to fix any failures found includes a "Fix" option, along with the check run input in the new actions input parameter:

    "actions": [{
        "label": "Fix",
        "description": "Let us fix that for you",
        "identifier": "fix_errors"
    }]
    
  2. GitHub surfaces possible actions for that check run in the pull request view.

    The user selects the action they want carried out. For example, they click Fix: Fix

  3. GitHub sends a webhook event to the app with the details of the user request.

    GitHub sends a check_run event with action of "requested_action" to the specific app. The payload includes the reference for the particular action requested by the user:

    "requested_action": {
      "identifier": "fix_errors"
    }
    
  4. The integrator's app carries out that action.

Use case

We used a linter app as a use case in the previous examples. This app needs write permission on the contents of the repository if you want it to apply the fixes and commit the changed code to the same branch. In GitHub, these changes might look this:

js-linter

To learn more about how an app can clone and access a repository for making changes, see "HTTP-based Git access by an installation."

How can I try it?

Anyone can register a GitHub App on GitHub through Settings > Developer settings > GitHub Apps and manage an existing GitHub App from the same place. See how to get started building GitHub Apps.

For more details, refer to the full Checks API documentation.

To access this functionality, you’ll need to provide the following custom media type in the Accept header:

application/vnd.github.antiope-preview+json

Share your feedback

We're excited to see what you build with these new improvements. If you have any questions, please let us know.