General questions about integration



I’m planning a new web application that will enable Github users to improve the way they work with repositories and branches.

I’m not really clear though on whether I should design this as an OAuth app or Github app, I have read the documentation but still have questions.

The app must support the following

  1. Expose controls which are restricted by the user’s own Github account settings.
  2. Receive webhook events.
  3. Support organization as well as user/repo specificity.

So I want an org-admin (when using the new app) to be able to perform actions that are only allowed because they are an org admin.

Non-admin users won’t be able to perform actions disallowed by their org membership restrictions.

For example user’s of the app may get the ability to create a pull-request or may get the ability to merge a pull request, which of these they can do is to be wholly dictated by their Github userid and its defined limitations.

Is this best built as a “Github app” or a “OAuth app”?

Are there ways to “make the app look” like it is part of Github - to the user using it?

I guess the app is a kind if project management assistant if that helps to convey what I’m doing.

Any info is much appreciated.


Hi @Korporal,

At first blush, I think that a GitHub App would be a better fit for this.

I wrote a bit about the difference between GitHub Apps and OAuth Apps and why you might choose one over the other here: What is the meaning and purpose of the "Enabled For GitHub Apps" tag in some API endpoints?

The TL;DR is that since you want to operate on a repository (or a set of repositories), a GitHub App is a better choice, since if you create an OAuth app, then the user has to give permissions to the app to do these actions on any repositories, anywhere where they would be allowed to do this via the API. In general, people aren’t particularly happy about giving such broad permissions to an app on their behalf.

Expose controls which are restricted by the user’s own Github account settings.

GitHub Apps have two methods of authenticating. The first is as the app itself (also called server-to-server), the second is authenticated as the user (also called user-to-server).

It sounds like you would want to use user-to-server authentication as described here:

This means that the app would only be allowed to perform actions on behalf of the user in the case where both of the following are true:

  1. The app is installed on the repository
  2. The user is allowed to perform the action in the repository

Receive webhook events.

Both OAuth Apps and GitHub Apps receive webhook events.

Support organization as well as user/repo specificity.

GitHub Apps can be installed on organization-owned repositories as well as user-owned repositories.

Are there ways to “make the app look” like it is part of Github - to the user using it?

This is not possible whether it’s an OAuth App or a GitHub App. You will need to deploy your app somewhere, and if your app requires an interface, you would be in control of that interface.


Hi @kytrinyx,

Thanks for this information, its very helpful. With regard to my question about making an app appear “as part of Github” the question itself was prompted after I read about the Github app named ZenHub.

I assume ZenHub and similar project management app are implemented as GitHub Apps and use the user-to-server approach that you mentioned?



Also @kytrinyx I’m not crystal clear about some things, I’ve scoured the documentation and the web in general and have questions that I can’t quite get clear answers to.

Here they are:

  1. A GitHub App - This is ultimately an external web application that can interact with Github - yes?
  2. A Marketplace or Works With App are technically the same differing only in their conformance to GitHub’s program terms - yes?
  3. Can someone just create a GitHub app and make it available to users/customers without it being either a Marketplace or Works With app?
  4. Is there any advantage/disadvantage if they do make their app available this way?
  5. Would it be typical for a new app to begin as a Works With, then as adoption grows move the app “up” so to speak into a Marketplace app?

Although I’m a very experienced developer with a good deal of Git and GitHub knowledge, I’m new to the world of integrations and so on, hence my questions which may appear naive!

Many thanks.