GitHub has a developer API that provides third party services with a great way to connect to various repositories and integrate some useful features. Hakiri uses this functionality for two purposes: scanning code for vulnerabilities in your projects and setting up web hooks that ping Hakiri whenever new code is pushed to a repository.

There are three levels of permissions that Hakiri sets up depending on your needs:

Basic Access

Permissions Requested:

  • user:email

The most basic set of permissions that allows Hakiri to access your public repositories, public profile and email address (for initial sign up). Hakiri won’t be able to create web hooks or write to your repositories. The former can be an issue if you need your code to be scanned right when it’s pushed to the repo. Without web hooks Hakiri checks public repositories for changes once every hour and runs security scans if there was a code change in the past hour.

Open Source Dev Access

Permissions Requested:

  • user:email
  • read:org
  • repo:status
  • admin:repo_hook
  • admin:org_hook

This permission level is ideal for open source development. On top of basic permissions, Hakiri will request read access to your public organization repos. It will also need to be able to create web hooks (for timely scans) and pull request statuses (for future pull request scanning functionality).

Private Access

Permissions Requested:

  • user:email
  • admin:repo_hook
  • repo

The third level of permissions covers read and write access to public and private repositories. It also lets Hakiri create web hooks and pull request statuses. The obvious downside of this permission level is that Hakiri gains write access to all of your repositories and some teams are not comfortable with that. We would drop this requirement today if GitHub allowed read-only permissions for private repos, but it’s currently not available.

One way around this limitation is to add a collaborator with read-only permissions to your project and to use this collaborator’s account on Hakiri (you’ll have to setup web hooks manually). This technique is used by a lot of companies not only with Hakiri but also TravisCI, Gemnasium and many others.

The easiest way to update GitHub permissions is in your account. Hakiri will also prompt you with permission updates in other contexts on the projects page and after security scans if it can’t setup web hooks due to permission limitations.