New Checks API public beta

Today we're adding new functionality which allows integrations and GitHub to communicate more comprehensively about the checks run against code changes. These changes will improve your workflow by allowing you to view feedback from code checks directly in the pull request view, see the line of code causing a problem in the diff view, “re-run” checks, and more-all within the GitHub user interface.

Check run annotation

Instead of binary pass/fail commit statuses, integrators can now report more fine-grained outcomes, such as a neutral conclusion for more informational analysis or action_required if the integrator site requires the user's attention.

Check run conclusions

We've added first-class support for common workarounds, like the ability to skip or request checks via commit message, trigger checks with a dedicated check_suite webhook event, and set preferences for when checks are triggered.

Check run GitHub UI

Integrator workflows

Automatic flow

  1. By default, we will automatically send installed applications that have the checks:write permission a check_suite webhook event with the action requested. When an app receives this event, it should perform its analysis on the code changes.
  2. GitHub displays the apps that have been requested to run checks in the pull request view with a status of queued.
  3. An app creates a check run with a started_at timestamp and a status (typically in_progress) for each analysis check that the app performs.
  4. An app updates the check run and includes information about the output of its analysis.
  5. GitHub displays the output of the check run in the pull request view.
  6. Repeat steps four and five if needed. Apps can send data in stages until their analysis is complete—when it sends a completed_at timestamp and conclusion.
  7. GitHub displays all the check suites and runs data in the pull request view.

Opt out of the automatic flow

Because some checks may be expensive to run, an application can opt out of the automatic flow and instead create check suites to their preferred timing. Application owners can control this by setting their check suite preferences on a per-app and repository basis. People with admin permission on a repository can override this setting.

User workflows

Check requests via the API

The automatic flow prompts installed apps to run checks against the last commit in code pushed to a repository. A user can request to run checks for any given commit with the request check suites API:

POST /repos/:owner/:repo/check-suite-requests

Check requests via commit message

A user can control the check suite request flow on a per-commit basis:

  • To prevent a check suite from being created, include skip-checks: true in the trailers of the commit message.
  • To request a check suite, when automatic creation is disabled, include request-checks: true in the trailers of the commit message.

Note: the trailer would need to be on the last commit of a push. If you supply both trailers, skip-checks wins.

See skipping and requesting checks for individual commits for more information.

Check requests via the Web UI

A user can re-run a check run or entire check suite in the pull request view on GitHub.com.

Re-run a check run

When a user requests to re-run a check, a check_run webhook event is delivered to that app's webhook with an action of rerequested. The app is then expected to create a new check run for the given head_sha.

When a user requests to re-run a check suite, a check_suite webhook event is delivered to that app's webhook with an action of rerequested. The app is then expected to create a new check run for all its runs in that suite.

Questions

How do checks work with protected branches?

If the names of check runs are the same as the context of prior commit statuses, and those statuses were required, then the new check runs are automatically required. If a commit status and check run are created with the same name or context, both the status and the check run will be required.

If the names of the new check runs are different from the old commit statuses, the new check runs will need to be selected as required.

How are check runs different than commit statuses?

Commit statuses allow for a simple pass or fail state. Check runs allow for much more granular information: they can conclude as either success, failure, neutral, cancelled, timed_out, or action_required. Check runs are more flexible than commit statuses. You can update the lifecycle state by indicating queued, in_progress, or completed through the status field.

Check runs can be created as simply as a commit status with just a name and conclusion for the given commit. They can also include a variety of output data: textual information, images, and feedback on specific lines of code.

Is this supported in the GraphQL API?

No, but we plan to add support in the near future.

Who can use it?

The Checks API is only available to GitHub Apps through a new granular permission: checks.

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.

See the full Checks API documentation for more details.

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. Take them out for a spin, and share your feedback in our Platform forum. If you have any questions, please let us know.

Looking for a new app to use? Browse GitHub Marketplace.

Staying on Top of Changes in GraphQL

To provide a more seamless experience we prefer to continuously evolve our schemas rather than using API versioning. Continuous evolution allows us to iterate faster and provide our integrators with new schema members more often. We do our best to avoid breaking changes, but sometimes it's necessary to offer an unversioned API.

We strive to provide the most stable APIs to our integrators and to provide transparency about new developments. This is why we recently shipped the brand new Breaking Changes page, which announces future breaking changes to our GraphQL schema.

Internally, our engineers mark certain schema members as deprecated using a Ruby API on top of the graphql-ruby gem. Using the changes metadata provided by our engineers, we automatically compute removal dates and generate this breaking changes page, meaning you'll always get up to date information.

Along with the GraphQL Changelog, we hope this helps you build better and more stable integrations! If you have any questions or feedback, please let us know. Happy building!

The GraphQL API Now Supports GitHub Apps

GitHub Apps have been the preferred way to integrate with GitHub for nearly a year. The advantages over regular OAuth apps include granular permissions, as well as tighter control over where the Apps are installed. However, GitHub Apps could only integrate with GitHub using REST API calls.

The GraphQL API now supports requests made by GitHub Apps. This means that any query or mutation available in our public schema can be made by users authorized through a GitHub App. GraphQL is a great way to fetch data about a variety of resources in a payload that matches your request precisely. For more information on the advantages of GraphQL over REST, see "Migrating from REST."

Go forth and build amazing things! When you've finished, list your App in the GitHub Marketplace for the world to see 😉.

Announcing the deprecation of GitHub Services

GitHub plans on shutting down GitHub Services so we can shift focus to other areas of the API, such as strengthening GitHub Apps and GraphQL, and improving webhooks. The intention of GitHub Services was to allow third-party developers to submit code for integrating with their services, but this functionality has been superseded by GitHub Apps and webhooks. GitHub Services has not supported new features since April 25, 2016, and we plan to officially deprecate it on October 1st, 2018.

Move to webhooks using GitHub or OAuth apps

As part of the deprecation process, we need integrators on our platform to move from HTTP-based services over to plain webhooks. Webhooks are much easier for both users and GitHub staff to debug on the web because of improved logging.

We have been coordinating with our largest integrators to assist them in seamlessly transitioning from GitHub Services to GitHub Apps and webhooks. In order to move your integration over to plain webhooks, you can leverage either GitHub or OAuth apps. Both "Replacing GitHub Services" and "Differences between GitHub Apps and OAuth Apps" provide information regarding the differences between the two frameworks.

Learn more about replacing GitHub Services

To learn more about this deprecation or moving from GitHub Services to GitHub or OAuth apps, check out "Replacing GitHub Services". Each service will be unique, so we don’t have a single prescriptive process to offer, but we are available as a resource to your team. Please contact our Partner Engineering team with questions.

Deprecation timeline

  • May 31, 2018: Submit your intentions for migrating or replacing your GitHub Service.
  • October 1, 2018: GitHub discontinues allowing users to install services. GitHub Services will be removed from the GitHub.com UI.
  • January 31, 2019: GitHub stops delivering installed services' events on GitHub.com.

New User-to-Server endpoints for GitHub Apps

As part of the ongoing audit of the availability of REST API endpoints for GitHub Apps, we've enabled another batch of endpoints. For a complete list of endpoints enabled for GitHub Apps, see available endpoints and identifying and authorizing users for GitHub Apps.

Recently enabled user-to-server endpoints:

Deployments & Deployment Statuses

Git Blobs & Refs

Issues & Issue Events

Labels

Pull Request Review Events

Repo Collaborators, Commits, and Releases

Root

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

What about other endpoints?

We're actively working on enabling more endpoints. Check back on the developer blog for updates when new batches become available. If you have specific requests or feedback, come chat with us in the Platform forum.

Preview the new Vulnerability Alerts and Dependency Graph APIs and Webhooks

We're releasing a Dependency Graph API in GraphQL that enables you to retrieve information about a repository's dependency graph. But that's not all; we are also adding a lightweight Repository Vulnerability Alerts API in GraphQL so you can get your security alerts through the API. You can stay up-to-date with the most recent changes using a webhooks that trigger when alerts are created, dismissed, or resolved.

Dependency Graph GraphQL API

We're introducing a new connection on Repository called dependencyGraphManifests which enables you to retrieve data about a repository's dependencies. Public repositories have dependency graph and security alerts enabled by default. For private repositories, you’ll need to Allow access in the Dependency graph section of your repository’s Insights tab.

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

  application/vnd.github.hawkgirl-preview

Repository Vulnerability Alerts GraphQL API

We're introducing a new connection on Repository called vulnerabilityAlerts which enables you to retrieve data about a repository's security alerts.

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

  application/vnd.github.vixen-preview

Repository Vulnerability Alerts Webhooks

We're introducing a new webhook event for repositories called repository_vulnerability_alert. You can get webhooks for create, dismiss, and resolve actions.

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!

Additional endpoints available for GitHub Apps

  • April 17, 2018
  • Avatar for jch jch

As part of the ongoing audit of the availability of REST API endpoints for GitHub Apps, we've enabled another batch of endpoints. For a complete list of endpoints enabled for GitHub Apps, see "Available endpoints".

Recently enabled endpoints

The newly enabled endpoints available now include:

Organization Members

Teams

Pull Request Review Events

Pull Request Review Requests

Pull Requests

New user-to-server endpoints are available in these APIs:

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

What about other endpoints?

We're actively working on enabling more endpoints. Check back on the developer blog for updates when new batches become available. If you have specific requests or feedback, come chat with us in the Platform forum.

Self-serve Onboarding for the GitHub Marketplace

After looking through our queue of amazing tools waiting to join the GitHub Marketplace we've decided to simplify the process--and to this end we're giving developers the ability to quickly get an app on the marketplace and onboard themselves.

New and improved guide

We now have a micro-guide that explains everything you need to get setup on the GitHub Marketplace:

What if you've already started

If you're already building a Marketplace app then you may have noticed the changes we've shipped this week. There is a completely new interface that enables you to move at your own pace and walks you through all the steps to go live on the Marketplace.

Feel free to continue building and make sure you have 4 green checkmarks in the left panel before you re-submit. We cannot wait to see what you've been building!

Screenshot

For any other questions, feel free to contact us here.

Preview the Organization Project Permissions API

We're releasing new API endpoints to support the new organization project permissions system. These new endpoints will give you the same granular control over organization projects that you're used to having with organization repositories.

Organization project collaborators

Using the new organization project collaborator API endpoints, you can add, remove, review, and list organization project collaborators. You'll need admin access on a project to use these API endpoints, and they are only available to organization projects.

Organization projects on teams

Just like with repositories, you can add organization projects to teams, remove organization projects from teams, review a team's permission on an organization project, and list all the organization projects for a team. Adding and removing a team project requires admin access to that project, and these new endpoints are only available to organization projects.

New "Update project" parameters

The Update project endpoint has two new parameters: organization_permission and private. You'll need admin access on a project to make changes to these parameters, and they only apply to organization projects.

Preview period

To access these new and updated endpoints 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 methods 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!

Preview the new Hovercard API

We're releasing a Hovercard API that enables you to retrieve information contained in someone's hovercard using either GraphQL or REST. Use the subject_type and subject_id parameters to find out more about someone in relation to their pull requests, issues, repositories, and organizations.

REST API

To access the new Get contextual information about a user endpoint during the preview period, you must provide a custom media type in the Accept header:

   application/vnd.github.hagar-preview+json

GraphQL API

We're introducing a new connection on User called hovercard which enables you to retrieve data contained in someone's hovercard.

To access this new API during the preview period, you must provide an Accept header as well:

   application/vnd.github.hagar-preview

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!

Recent Posts

Subscribe to the RSS feed