This is an open letter to @github on behalf of third-party app developers.

For a very long time, permission scopes has been a common issue for both users and app developers.
These scopes are extremely permissive and far too broad, preventing users from using third-party applications.

We need a more granular permission system and we hope you listen to this.

Below you can find some examples that describes exactly what we mean by how flawed the system is and some suggestions to improve it.

gist scope

Grants write access to gists.

Let's say you want to build an app like GistBox to organize gists. In order to read read private gists you would need to request the gist scope.

Here's what users would see:

Even if you don't want to create any gists, you still need to request write access. Some users may find that ok, but other users can be afraid of having someone creating or editing their precious code snippets.

Solution: what if we had read_public:gist, read_private:gist, write_public:gist, and write_private:gist instead?

public_repo scope

Grants read/write access to code, commit statuses, collaborators, and deployment statuses for public repositories and organizations. Also required for starring public repositories.

Another example: let's say you want to create an app like Waffle, HuBoard, or ZenHub to manage your issues. In order to have a basic functionality like creating issues on public repositories, you would need to request the public_repo scope.

Here's what users would see:

Note how broad this permission is. These apps have no interest on wikis, deploy keys, webhooks, or anything like that. But still, that's the only way to go.

Solution: what if we had read_public:repo_code, read_public:repo_issues, and write_public:repo_stars instead?

repo scope

Grants read/write access to code, commit statuses, collaborators, and deployment statuses for public and private repositories and organizations.

Finally, the issue I'm personally facing right now. Let's say you want to build an app like DevSpace to read public and private events. For this we'd have to use the repo scope.

Here's what users would see:

This is probably the most shocking permission scope. Even though we don't want to write anything we'd still need to request a permission that can change code, issues, and many other important things from private repos.

Solution: what if we had read_public:events_repo, read_private:events_repo, read_public:events_org, and read_private:events_org instead?

You see, those are just few examples, there are many other apps facing the same issue:

• https://github.com/ZenHubIO/support/issues/77
• https://github.com/waffleio/waffle.io/issues/1957
• Access and permissions huboard/huboard#203
• Huboard asks for wider permissions than it needs huboard/huboard#468
• github permissions astralapp/astral#1
• Limit permissions astralapp/astral#11
• Login via GitHub prompts to authorize application to access private organization data and modify public organization data mozilla/science.mozilla.org#11
• Read-Only OAuth Scope on GitHub, Please? jollygoodcode/jollygoodcode.github.io#6
• https://github.com/thoughtbot/hound/issues/925
• Permissions scoping bkeepers/github-notifications#146
• 3rd Party App Permissions - Read and Write Public and Private Repos? holman/ama#635
• Add separate privilege to organization teams for issue management isaacs/github#268
• Fine grain control over team permissions isaacs/github#311
• Gist OAuth scope is too permissive isaacs/github#31
• https://twitter.com/iandees/status/692855774645604359
• https://twitter.com/jasontrill/status/690813850350854144
• https://twitter.com/omarqureshi/status/655148749019303936
• https://twitter.com/YAMPST/status/623204972029734914
• https://twitter.com/codingjester/status/613019497549705217
• http://blog.waffle.io/updated-permissions/
• https://gitter.zendesk.com/hc/en-us/articles/200176672-Authenticating-with-GitHub
• https://blog.outlearn.com/shortcomings-of-github-oauth-for-multiple-scope-permission-levels-d4e959d2c6fe

@syropian, @ashumz, @acroca, @drusellers, @burtonjc, @pierrebeugnot, @rauhryan, @homeyer, @sxgao3001, @marydavis, @nparsons08, @zhangchiqing, @wbeard, @jamie, @diophore, @glenngillen, @troy, @winston do you agree?

I love GitHub and I hope this discussion contributes back to their product. There's a lot of potential on this community and I believe we can make a change.