We love @github. Our processes all revolve around GitHub.

Naturally by extension, we love the GitHub API, because it allows us to do creative things with GitHub.

So far, we have built a few apps that rely heavily on GitHub's API:

• deppbot
  • A service that does automated dependency updates for Ruby apps, issued as Pull Requests
• Dasherize
  • A simple dashboard for CI and GitHub stats
• GitHub Gem Stats
  • A toy app for "Which RubyGems does X use?" and "Which GitHub repo uses Y gem?"

Let's talk about permissions next.

For both deppbot and Dasherize, we require access to both public and private repos.

Looking at GitHub's OAuth scopes, we'll need to use the repo scope.

Hmm.. But wait a minute.. The repo scope grants read AND write access to basically everything! Getting read access is probably a must for all apps, but do we need write on everything?

Due to the nature of deppbot, we'll need write permission on public and private repos, so that it can issue Pull Requests when it finishes the dependency update for a project and perform other actions.

However, all Dasherize does is read from public or private repos, and it's not doing any write at all. You can even take a look at the source code to verify that.

So isn't it intrusive to require write permission too? Definitely.

As a user, I would like all apps to only require the lowest level of permission that it needs to operate.

As a developer, I am taking on unnecessary liability when my app has permissions that it doesn't need.

Of course, we are not the first to create apps that use GitHub API, and this has been a common issue for both users and app developers for a while, for example:

• http://docs.codeclimate.com/article/258-do-i-have-to-grant-code-climate-read-write-access-to-all-of-my-github-repositories
• https://groups.google.com/forum/#!topic/travis-ci/ihZZXAw9K6M
• Hound keep asking write permission to all data of public repositories (security/dangerous) houndci/hound#925 (comment)
• https://gitter.zendesk.com/hc/en-us/articles/200176672-Authenticating-with-GitHub

By design, GitHub API does not provide any Read-only OAuth scope for public and/or private repos. Once you ask for permissions to either public and/or private repos, you'll get both read and write. What can we do then if we just want Read-only access on GitHub API?

There are definitely work arounds, as mentioned in some of the links above:

Progressive Permissioning

This means that the app shall only ask for permissions when it requires it.

Let's use @houndci as an example.

When you first sign up, @houndci only asks for access to your email and public repos read/write.

Then, it provides you with the option to "Include Private Repos".

Clicking on that, you can now grant @houndci access to both public and private repos read/write.

In this way, you only grant @houndci necessary permissions when it requires it.

But this still doesn't solve the problem if my app just requires a read scope, like Dasherize..

Manual Setup

Alternatively, maybe a manual setup of collaborators might help?

Unfortunately not.

When you add a collaborator to a GitHub repo, the collaborator naturally has read and write permissions, and you can't change it.

What about Teams (for Organization repos only)? Can it grant Read-only permissions?

Yes. That might help!

You can create a special Team in the organization, grant the Team a read-only access to the repo,
and now you have a Read-only scope. But in most cases, manual setup is not the best UX experience. 😢

Recently, GitHub also added Read-only Deploy Keys, as another option to grant Read-only access to one single repo.

Many are speculating that this eventually lead to a Read-only OAuth scope. I sure hope so.

In summary, we really hope that @github can provide developers with a Read-only OAuth scope, so that app developers don't have to explain ourselves every time we use the repo scope.

In both deppbot and Dasherize, we are conscious of our decision in asking for read write access to public and private repos because we went with the simplest solution for now to validate the ideas. Definitely, we should look into both Progressive Permissing or Manual Setup when the apps get enough traction and feedback from users.

Thank you for reading.

@winston ✏️ Jolly Good Code

About Jolly Good Code

We specialise in Agile practices and Ruby, and we love contributing to open source.
Speak to us about your next big idea, or check out our projects.