Installation Flow


I’m interested to know what the GitHub’s thoughts are on the ideal flow for an Integration installation… We need to know the users email address, allow them to choose some settings for the integration and pay per repository.


  • Are other integrations also getting folks to sign-in with OAuth in order to get contact email address?
  • Post-installation unfortunately GitHub doesn’t give any calls to action or forward back to the integrations website - how do we complete the flow? Ask for settings and payment? Especially if they come from the integration directory.

This would all be much simpler if we could show a list of repos on our site and have them pay and install from there - however I don’t think you can do this without asking for private repo access through the old API’s.

Kickstart the addition of an "integration" from own app

Hey @tommoor,

Given this is an Early Access, and we’re not recommending production shipping to end users just yet, I don’t know that many other integrators have crossed these bridges just yet.

Are other integrations also getting folks to sign-in with OAuth in order to get contact email address?

Before this project reaches production release, we do plan to add the ability for you to receive a customer email when an integration is setup.

Post-installation unfortunately GitHub doesn’t give any calls to action or forward back to the integrations website - how do we complete the flow? Ask for settings and payment? Especially if they come from the integration directory.

I’d love to hear more about what you need on your side during the setup process. As you mentioned, due to the nature of the per-repository installation system, that part of the setup process must happen on the GitHub side, but I’m curious to hear your thoughts around the any additional steps beyond that.


Hey - So, two things that would help a lot in allowing us to show the correct info to users:

  • Allow us to provide a post-installation url that the user would be sent to after setup.
  • Provide an endpoint to get installations that a user has access to, or better still given an integration_id and a user_id an endpoint that returns the intersection of repos that both have access to.

Kickstart the addition of an "integration" from own app

IMO something like this is essential. Otherwise asking for payment details or allowing settings config is too complicated.


Thanks for the additional thoughts @tommoor and @fjsj. Those additional steps are definitely something we want to make more seamless. We’ll keep those specifics in mind as we look into this.

Kickstart the addition of an "integration" from own app

I have not received an early access yet. I would like to know if there will be an option where the installation will trigger a redirect to a prespecified url instead of starting the auth right away, as we need to know people who are enabling the integration also have an admin access in our product. So, the kind of flow which we want is like this
1.Github redirects to our url
2.User signs in or creates an account in our product
3.we initiate the auth flow.
4. The user comes back to our page.


@jmilas any update on this one? Two months down the line here… I feel like we can’t even start using these API’s until it’s possible to have a reasonable installation flow.


the current installation flow really is not good. the users get lost after they install because they don’t have the url to go back to. it is in the github UI but it’s small and not obvious. we really need to get this fixed ASAP!! pretty please!! :slight_smile:


Agreed with what has been said. The current workflow is kind of hard for the users and really different from the existing OAuth. Furnishing a next callback URL parameter to the installation page would most likely do the job.

It would be awesome if we could have it directly on the install page for a specific account, ie:

and propagated from the account selecting page to the next:

Between the two of them, the first one (callback URL on the account install page) is the most important for us.


We are struggling with designing our new Github integration for the same reasons. Here are our thoughts:

TLDR; We think it’s in everyone’s best interest for Github to enable OAuth applications to add integrations to repositories.

We see the root cause of many issues (from this thread and others) to be the issue explained by @jmilas: OAuth is scoped at the account level, and integrations/installations are intended to be scoped to the repository level. Indeed, we recognize the incompatibility of scopes to be a quandary. Integrations were clearly intended to address the “Over-scoping” complaints present with OAuth. That intention seems to make enabling “Over-scoped OAuth” to add the “Limited-Scope” integrations seem silly.

Despite these factors, it seems clear that the majority of third parties who would use integrations will likely wish to initiate the flow from their application. The reason the OAuth flow has been so successful is that it targets and addresses this most common use case. While we acknowledge the challenge and reasoning behind the decision, the reality seems to be that the current vision and design do not meet the needs of the EA developers who are trying to do very normal things.

With that said, it is most certainly possible for Github to add this functionality, which would solve the needs of everyone in this thread. It is only a matter of a design decision by Github not to do so. We agree that Github should continue to work out a full-featured OAuth-free workflow over time because it’s valuable. However we don’t agree that adding integrations via OAuth should be forbidden for several reasons. At the very least, it violates the principle of least surprise. Using the OAuth flow, an application can be granted rights to perform virtually any operation on a repository, including deleting the repository or adding a webhook to it. However, adding an integration to a repository is forbidden which appears arbitrary and short-sighted on the surface.

Objectively speaking, it seems like the type of controversial decision Github will be trying to justify to the community indefinitely, and will keep coming up in the forums. It makes sense from one point of view, but doesn’t make sense from most points of view.

It’s worth noting that we’ve set up our applications to use both OAuth and Integrations because they solve different problems. We are using OAuth to enable the user to authenticate to our application using Github credentials and create issues. At the same time, we are using integrations for performing repository operations because it has advantages like auto-creating webhooks, and the token scheme is better. The only thing that is unpleasent is that we have to tell the user to go through two integration processes, and that’s what we’d like to see changed.


@solvingJ totally agree, glad to see you write the issue out with clarity. FWIW we totally stopped development of our github integration until this is resolved as I believe it’s untenable from a user UX perspective.


Thanks for the feedback Tom. Glad to hear we’re not alone. We’re now just eager to see a preliminary response from Github.


@jmilas, can you let us know the ETA to allow adding integrations via OAuth?


Hey All,

Thanks for all of the feedback on this topic! Sorry for the delay as we considered the best way to implement these requests.

I wanted to let you know that we plan to allow you to specify a URL to which we’ll send users after they complete the GitHub portion of the Integration Installation. This should allow you to perform any additional setup process on your end. We’ll also provide a flow for you to identify the GitHub identity of this user so you can map the user (and the installation) to your system as needed.

We don’t have an estimated timeline for when this will be added, but we’ll keep you updated when we do.

:notepad_spiral: Also just a small reminder since a few comments mentioned this being a blocker to using Integrations more widely with a user base (which is really helpful to know), per our Early Access descriptions, this type of release isn’t intended to be used in your full production environment just yet as we continue to change, improve, and add functionality.

Installing integrations on multi-tenant apps

Hi jmilas,

It is good that Github is moving forward with improving the flow from the Integration Installation pages.

Can you please comment also as to whether or not the team has at least discussed the recommendation made above.

Specifically: Permitting OAuth applications to add an integration using the traditional OAuth workflow.


@jmilas thats great, we would want to use that “redirect to app after installation” as it would help with the installation flow.

We are also curious to know if there are plans to allow an oauth request to also install some integrations. It would allow a quicker installation flow for a first-time users: rather than having to go through github’s UI for both OAuth and integration installation. So we are looking forward to more details on this plan.


Hi @jmilas, any new information regarding the redirect after installation, or the request to allow OAuth to perform the installation flow?


Hi everyone,

The setup_url is now available in the GitHub UI when you edit or create an Integration. It’s an optional parameter which will redirect users to the specified URL after they install your integration. We’re working on adding this to the documentation but here’s a screenshot of where you can find this setting.


That’s great @sbarnekow! Do you have some info on what payload data github will send to this url? IntegrationId, InstallationId, etc?


Hey @acrobat for now we’re just appending the installation_id to the setup_url once we send them to your site. If you have more feedback or find other params may be useful, please let us know!