Preview Review Requests API

Today we're releasing an addition to the Pull Request Reviews API, the ability to manage Review Requests!

To access Review Request API during the Early Access period, you must provide a custom media type in the Accept header:

application/vnd.github.black-cat-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 Pull Request Reviews API

Today we're releasing a preview API for Pull Request Reviews!

To access the Pull Request Reviews API during the Early Access period, you must provide a custom media type in the Accept header:

application/vnd.github.black-cat-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!

Snyk's Journey from CLI to GitHub Integration

This post is penned by Guy Podjarny, CEO & co-founder at Snyk - for the interest of the GitHub community

At Snyk, we help developers fix vulnerabilities in open source packages, such as npm and RubyGems. Snyk started as a CLI tool to support source code management as well as build and test tools. However, running an application in the terminal is fundamentally limited in terms of scope and UI, which led us to create a deeper integration with GitHub.

Less than 6 months after launching the integration, we now see the integrated GitHub experience as far superior to the CLI. This post shares why we integrated with GitHub and how it helped - which might benefit others facing similar choices.

How GitHub helped us simplify

Unlike changing your tool of choice for CI or linting, using Snyk means introducing a new activity to your dev flow. Developers have very little time to spend on additional activities, and so we put a lot of effort into making our CLI easy and intuitive, demonstrating value in seconds. While user feedback shows we succeeded in doing so, even a perfect CLI could not address some of the challenges we came across.

Integrating with GitHub was focused heavily on breaking through these challenges, further shrinking time to value and simplifying continuous integration into the dev workflow. Here are the key ways our GitHub integration helped this goal.

Get value without leaving the browser

Most developers discover Snyk via the web (e.g. through a badge), but to use the product they had to leave the browser and go to the terminal. This may seem easy, but it's still another step, and many visitors dropped off at this point. Integrating with GitHub let users see the value immediately (for example, find or fix vulnerable packages) without leaving the browser, which reduced the drop-off substantially.

Broad repository access

Snyk's CLI is easy to use on any given project, but running it on every repository requires more effort. As a result, we noticed many users didn't test all of their application, but only a select few. With our GitHub integration, we automatically identify the repositories we can protect and test all of them at once. A single click uncovers vulnerabilities in all repositories at once, driving the right behavior with increased ease. For more information, see "Get a repository."

Separate and persistent code changes

Snyk's CLI improves projects by fixing code (mostly package files) through discovered vulnerabilities. We noticed that changes not committed immediately are often forgotten forever. With GitHub, we can submit the same fixes as a well documented Pull Request, which doesn't go away until it's merged or closed. Pull Requests also allow us to proactively submit fixes to newly discovered issues, as opposed to emailing developers and requiring them to run the CLI to produce the necessary changes.

Single click integration

Lastly, while the CLI made a one-time test easy, many users didn't integrate the vulnerability testing as part of their CI process. As before, this isn't a complicated step, but it's yet one more thing users might forget. Integrating with GitHub, we've enabled developers to use their existing GitHub Flow and bring in Snyk with a single click. We embed the test logic in the Pull Request checks, and listen to commits to track the project's dependencies. This improvement did wonders to the number of users who made security testing a continuous activity.

Spreading the word

While secondary to ease of use improvements, the GitHub integration also helped grow awareness and visibility of Snyk and the problem it solves. We didn't really plan for it, but as a company solving a new problem it proved very helpful.

Pull Request visibility

Submitting Pull Requests was the best mechanism for growing awareness within the team. When we submit a Pull Request fix, everybody dealing with the repository can see it - not just the champion who integrated Snyk in the first place. Team mates get the opportunity to learn the problem existed, see how it was solved, and sometimes even act (merge). Beyond team members, public repository watchers are also notified about these Pull Requests, and we've often seen users comment asking for a Pull Request to be merged.

Integrations directory

Integrating with GitHub also meant being listed on their new-ish Integrations Directory. GitHub customers consult this directory when looking to bolster their development workflow with tools, and finding Snyk with that mindset makes them likely to act. The integrations page still a fairly modest traffic source for us, but GitHub is now proactively encouraging users to explore it, and we look forward to seeing it bear fruit!

Badges

In addition to being a platform, GitHub is also a social network, making it a great vehicle to spread the word about the problem and solution. To that effect, Snyk offers badges, indicating the number of vulnerable dependencies this project has. The badges have been very helpful in growing awareness, and users that click the badge and land on a Snyk test page are far more likely to register than those arriving through other venues.

Consistent workflow

What constitutes a good CLI tool differs by the programming language and surrounding dev tools. GitHub Flow, on the other hand, remains mostly consistent across languages. This dramatically reduces the client-side effort of adding another language, allowing us to expand our reach and value. The difference in effort is so big that we've decided to only support GitHub when we launched our initial Ruby support, buying over a month before also releasing CLI support

Integration challenges

Technically, integrating with GitHub wasn't terribly complex given the well documented API and many open source examples. Where we did encounter challenges was with authentication and access scopes.

Separating authentication from repository access

We actually integrate with GitHub twice - once for user authentication and another for repository access. This separation can be confusing to users who are prompted to give GitHub access twice. After many conversations we decided to keep the separation between authenticating a user and granting repository access, to allow future flexibility. To reduce confusion, we added an interim screen before the second OAuth screen, and are repeatedly tracking activity and tweaking our UI flows.

Overly broad repository access scope

GitHub's current OAuth scopes for repository access are very coarse. For instance, adding a webhook means requesting permissions for all repositories instead of a single repository. In fact, Snyk doesn't even need access to source code except a specific set of files, but GitHub OAuth forces us to require full access. This is the single biggest complaint we get, and the biggest drop off point in our flow.

At the moment, we compensate for this shortcoming using a self-hosted broker and our CLI. In addition, GitHub has recently launched early access to a new Integrations API, which gives users more control over which repositories and files an app can access. We plan to switch to this new API, and expect it to mitigate this concern substantially.

Summary

Creating a tight GitHub integration was one of the best decisions we've made to date. It helped us dramatically reduce the effort to start using Snyk, and let us guide users into using it correctly with minimal effort. In addition to usability, the integration also raised our visibility across the dev team and repository users, helping us spread the word. Lastly, the consistent GitHub workflow helps us expand faster into new languages, making us relevant to more developers and providing more value to existing users.

The integration was not without its challenges, and required a fair bit of UX design and implementation details to get right. However, the effort was more than worthwhile, and we intend to keep the integrated path as a core direction.

If you have a CLI tool, you should consider adding a tight GitHub integration too. And if you're using GitHub, don't forget to test your repositories for vulnerable dependencies too!

Update to Protected Branches API Preview

A few months ago, we released Pull Request Reviews at GitHub Universe. We're now updating the Protected Branches API with the ability to enable and disable required pull request reviews.

This will be a breaking change, but to make the transition easier, we've decided to not require you to explicitly include required_pull_request_reviews object on the general update branch protection endpoint until the preview period is over. At that point, if you do not include the required_pull_request_reviews object, you will receive an error.

How can I try it?

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

application/vnd.github.loki-preview+json

Take a look at the docs here. If you have any questions, please get in touch.

New Webhooks for Collaborators, Members, and Teams

We're releasing new webhook events for repository collaborators, organization members, and teams. You'll automatically begin receiving these events if you have a webhook that is subscribed to wildcard events. As always, we continue to recommend listening for the actions in order to future-proof your code.

The new events and actions are detailed below.

MemberEvent

• edited: sent when a collaborator's permissions change for a repository owned by an organization.
• deleted: sent when a collaborator is removed from a repository.

OrganizationEvent

• member_invited: sent when a user is invited into an organization.
• member_added: sent when a user is added to an organization.
• member_removed: sent when a user is removed from an organization.

TeamEvent

• created: sent when a team is created.
• edited: sent when a team's permissions change.
• deleted: sent when a team is deleted.
• added_to_repository: sent when a team is added to a repository.
• removed_from_repository: sent when a team is removed from a repository.

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

Preview the new Organization Memberships APIs

We're releasing new endpoints and changes to existing endpoints to better help you administer your GitHub organizations and repositories.

New endpoints

• Review a user's permission level
• List outside collaborators
• Remove an outside collaborator
• Convert a member to an outside collaborator
• List pending organization invitations
• List pending team invitations

Changes to existing API endpoints

• The default_repository_permission and members_can_create_repositories settings for an organization can now be retrieved and set through the Get an organization and Edit an organization endpoints.

• The Create team endpoint now offers the maintainers parameter which will allow you to add team maintainers upon creation.

• You can now use the affiliation parameter with the List collaborators endpoint to filter a repository's collaborators by their affiliation type.

To access the Organization Membership APIs during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.korra-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!

Changes to the upcoming Projects API

To support the release of organization-wide projects, we're making a change to the upcoming Projects API.

New Projects API endpoints

We've added new "List organization projects" and "Create organization project" API endpoints, allowing your app to get all of the projects belonging to a particular organization, or to create new ones.

Changes to existing Projects API endpoints

Previously, the "Get a project" endpoint was scoped to the project's owner. It looked like this:

GET /repos/:owner/:repo/projects/:number

We're changing the "Get a project" endpoint to look like this:

GET /projects/:id

This allows integrators to keep the same URL structure in their API requests whether they're working with a repository project or an organization-wide project.

We're making this same change to every single Projects API endpoint except for the "List repository projects" and "Create repository project" endpoints.

The owner-scoped endpoints (besides those for "List repository projects" and "Create repository project") are now deprecated, so please update your apps to use the new endpoints before November 10, 2016. On this day, we'll be removing these endpoints. Further requests to them after this day will receive 404 responses.

New scope requirements

We've added the public_repo scope as a requirement for accessing projects that belong to a public repository. This is in addition to the existing repo scope requirement for accessing projects that belong to a private repository or an organization.

Here's how this new public_repo scope requirement will affect the Project API endpoints:

• The new ID-based project API endpoints will require the public_repo scope for projects belonging to public repositories effective immediately.
• The "List repository projects" and "Create repository project" endpoints will begin requiring the public_repo scope for public repositories on November 10, 2016.
• The deprecated owner-scoped Project API endpoints won't require the public_repo scope for public repositories, but these endpoints will be removed on November 10, 2016.

To access the Projects API 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!

New Webhooks for Labels and Milestones

We're releasing new webhook events for labels and milestones. You'll automatically begin receiving these events if you have a webhook that is subscribed to wildcard events. As before, we continue to recommend listening for the actions in order to future-proof your code.

Several new events and actions were added, which are detailed below.

LabelEvent

• created: sent when a label is created.
• edited: sent when a label is edited, such as when it's renamed or the color is changed.
• deleted: sent when a label is deleted.

MilestoneEvent

• created: sent when a milestone is created.
• closed: sent when a milestone is closed.
• opened: sent when a milestone is opened.
• edited: sent when a milestone is edited, such as when its description, due date, or title is changed.
• deleted: sent when a milestone is deleted.

IssuesEvent

• milestoned: sent when an issue is added to a milestone.
• demilestoned: sent when an issue is removed from a milestone.

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

Traffic API Preview now has ISO 8601 compliant timestamps

We've updated the Traffic API preview to make the timestamps ISO 8601 compliant. For example, the millisecond timestamp 1475625600000 will be changed to 2016-10-05T00:00:00Z.

This is a breaking change for the views and clones endpoints. If you're trying out this new API during its preview period, you'll need to update your code to continue working with it.

As always, if you have any questions or feedback, please get in touch.

OAuth authorizations grants API is now official

We're making OAuth grants API part of the official GitHub API. The grants API simplifies management of OAuth applications by letting you view and revoke access in a similar manner to how users manage OAuth applications on GitHub.com. Rather than managing individual OAuth application tokens, the grants API allows you to view and revoke all access for an OAuth application you had previously authorized.

During the preview period you needed to provide the application/vnd.github.damage-preview preview media type in the Accept header to opt-in to the changes. Now that the preview 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!