Installation Flow


When adding a URL (eg - different domain though) to the Setup URL on the integrations page, I click Save changes, the screen returns the list of integrations, and I click that integration again - but the Setup URL field is blank.

Whether the installation is installed or not, the issue still occurs, it’s a private integration (for dev/testing).

It has the correct effect though, on installation the user is redirected to the Setup URL, so I assume it’s just a display issue.


An extra param to help identify and authenticate the user with GitHub would be helpful. I would make possible to check if the person has access to that installation (and didn’t crafted the URL on its own) without having to add the OAuth2 flow between the installation and the setup_url.

I was going to refer to something similar to but this guide was taken offline.


Hey @bradleyfalzon are you still seeing this issue? I just attempted to replicate in Chrome but didn’t experience the same behavior. Which browser are you using?


Thanks for this feedback @lucasmazza! Keep an eye out in future weeks for more on the user identification flow.


No @sbarnekow I’m not having the issue anymore, I did consistently ~24 hours ago, but can’t reproduce anymore. I’ll put it down to a client side issue. FYI I was using Firefox at the time, I hadn’t tested Chrome at that point.


I’m not able to make the setup_url work on Chrome (Version 57.0.2987.133 (64-bit)). I’ve provided it on my integration. When I click install, nothing happens. However in my console I see

Refused to send form data to 'https://REDACTED_URL/?installation_id=20228' because it violates the following Content Security Policy directive: "form-action 'self'".

Same integration works from safari.


For a multi-tenant integration can the installation be triggered from their application page with some unique payload/token that could then be sent back to the callback URL with the installation id and a way to identify the user so that the integration can continue the setup from where it stopped.
This might also allow the integration to ensure that user has access to the integration installation as well.


I’m trying to use setup_url and encountering the same issue as @clintam. It looks like Github’s CSP header prevents form submissions outside of the domain, so POSTing to the setup url doesn’t work:

$ curl -sI | grep Content-Security-Policy | grep -Eo "form-action[^;]*"
form-action 'self'


Hey @clintam and @hmarr; I shipped a fix for the setup_url issue you’re experiencing in Chrome. Please give it another go!


Is there any update for this? Other than pushing the user through an OAuth flow once they land on the setup URL we don’t have any other way of identifying them in our system or in GitHub’s. Ideally, the setup URL would be passed a code= parameter so we could query GitHub for the user’s info and log them in or sign them up in our system.


Moving from a POST to a GET has fixed it - thanks!


@coryvirok for security, you need to identify users via the OAuth flow outlined here:


I’m still finding this to be the most problematic part of implementing a GitHub app. It appears that perhaps GitHub thought that installing on GitHub was the most likely path (or maybe the straightest path for now), but we expect users to kick off an install process from our own application.

Two things could make this process easier for us:

  • A redirect URL that is not the same for every user. Allow it to be supplied as a query parameter to GitHub so that we can redirect the user to a dynamic route.
  • A simple code parameter that can serve the same purpose. Even if the redirect URL remains the same, we can use the code to correlate the initiation.

As of right now, the only method I can come up with that works is something like this:

  • Have the user connect with GitHub and store their GitHub id
  • Have them install the application and provide a redirect URL in the application’s settings
  • The user’s GitHub id saved earlier in the process is then matched up with the sender of the webhook from the installation, completing the process and giving me enough information to redirect them within my own application appropriately.

The above means that I have to do some pretty complex asynchronous work in my UI and on my server, or force the user to manually refresh to see if we have the data from GitHub matched up correctly. This also means the users must match, and the user cannot kick off a separate installation. We have to do some pretty defensive coding, which is significantly bloating the time involved in making this integration possible.

Please let me know if I’m misunderstanding anything here, or if my suggestions seem sensible.


Thanks for the detailed and thoughtful feedback, @JoshSmith :zap: – I’ve shared this with the team internally and asked if they have any advice or thoughts on improving that flow. We’ll followup here as soon as we have anything new to share. :bow:


Thanks, @izuzak! If you want some more detail on our current plans to make this flow work, you can always check out this issue. We’ve broken down how we’re planning to handle the whole lifecycle, and some more edge cases that are brought up under this flow. It may even help (at least in the short term, pending no changes to the flow from your team) for future integrators to consider how to handle some of those edge cases.


Hi team, we are also hitting the exact same issue JoshSmith mentioned in Installation Flow.

A similar design to the standard OAuth2 flow, where states can be passed to GitHub then back to our server with callback would be great.

Is there any updates on the progress/solution here?


We’d love to see a token option here too, that is either returned in the webhook event, or on the setup url.

Without it, it’s feasible that an app installation can be hijacked under certain conditions.


@keavy, can you elaborate a little more on that security need please?

The user needs to be logged in to GitHub in order to install the app. So they’re already authenticated and real as far as GH is concerned. Sending that user to setup_url takes them off your domain and onto mine, so I promptly launch the oauth flow to send them back to your site, which sends them back to mine (this time with some details of who they are).

This is pretty terrible UX, but setting that aside, I don’t see how it’s required for security (if anything, I thought it’d increase the attack surface by making things way more complicated??. Have I missed something? Transmitting a user/org handle in plain text url encoding wouldn’t be good, but this could be encoded and verified (e.g. the same way as a webhook is secured).

Alternative thoughts about the flow - what about a workflow where GitHub POSTs data (user_handle, org_handle, installation_id etc) to the setup_url endpoint, then expects a redirect_url as the response, to which it can redirect the user. Thus in the architecture of our GitHub apps we’re separating the user views from the github integration views, which seems to me to be cleaner and allows much more flexibility as far as the content of the redirect_url goes.


Thanks for the continued conversation here and the detailed use cases and ideas you’ve shared. I just wanted to let you know that we’re considering the needs you all have laid out here and we’re working to determine if there are solutions that make sense to improve this process and address the feedback you’ve shared as part of our current planning for upcoming improvements.


Hi GitHubbers! I just wanted to check in and see if there’s been any movement here.

We would still love to implement something like a:

  • dynamic redirect URL
  • a code param

Are any of these options, or something similar, under consideration right now? If so, do you have a sense of anticipated timeline so we can do some backwards planning from there?

Thank you!

Installation redirect URL needs extra parameters