[Self-hosted] Allow projects to work with github.com the same way they do for GHE

[jldec]

Self-hosted users cannot easily use Gitpod projects with github.com because there is no straightforward way to configure the Gitpod GitHub App to work with a self-hosted Gitpod instance.

This is one example of issue #8536.

Would it be possible to enable SH Gitpod users to work with github.com using the GHE flavor instead of always requiring a full GitHub App for any Gitpod that talks to github.com

Yes -- we currently have a hard-coded if (host === "github.com") that could be made smarter, e.g.

if (host === "github.com" && hasApp) {
  useApp();
} else {
  useWebhooks();
}

[jankeromnes]

Happy to implement this if/when we schedule it.

[jldec]

Another customer is asking (see internal)
The alternative until we have a GH App config admin UI would be to document the steps from here.
cc: @geropl

[geropl]

@jldec @jankeromnes I talked to Chris about this yesterday. There are ideas to externalize all kind of "admin" config surface from the app. Those have not been populated/discussed, yet, so take this with a grain of salt.

For this issue it basically means: Let's do the minimum to make it work for self-hosted for now. And I learned yesterday that we in fact still have the view that would let you configure this "on installation". Maybe that's good enough for now, and the examples @mrsimonemms shared are mis-configured? 🤔

[jldec]

scheduled, since this unblocks self-hosted users who want to try working with github.com.
cc: @jankeromnes

[rgoldfinger-quizlet]

The alternative until we have a GH App config admin UI would be to document the steps from here.

Any chance you should share these steps? It would help us get unblocked.

[jankeromnes]

@rgoldfinger-quizlet Sure, I can share these steps below.

However, note that the process is a little bit convoluted, and we'll soon ship a fix that makes github.com "just work" like any other Integration when you don't have a special GitHub App set up. I'd strongly encourage waiting for this upcoming fix instead of attempting the below.

How to integrate your Gitpod installation with a GitHub App?

Requirements

• You'll need to create your own GitHub App (see instructions below)
• Have a working Gitpod installation and its URL
• Have a working kubectl connected to your Gitpod installation

Creating a GitHub App

To connect your Gitpod installation with a GitHub App, you first need to create a new GitHub App (apps can only be pointed to a single Gitpod installation, and a Gitpod installation can only work with one single GitHub App).

This can be done like so:

1. Open https://github.com/settings/apps/new
2. Give your app a recognizable name (e.g. Gitpod-<yourname>)
3. (Homepage URL can be your website or anything else)
4. Set the Post Installation Setup URL to https://<FIXME>/api/apps/github/setup (but replace <FIXME> with the hostname of your Gitpod installation)
5. Check Redirect on update
6. Set the Webhook URL to https://<FIXME>/api/apps/github (same as above)
7. Set the Webhook secret to a random value (for our example, we'll use secret, but please use a different value)
8. Grant the following Repository permissions:
   1. Contents: Read-only
   2. Metadata: Read-only
   3. Pull Request: Read & Write
   4. Commit Statuses: Read & Write
9. Subscribe to events:
   1. Pull request
   2. Push
   3. Repository
10. Finally, allow the app to be installed for Any account and create the app
11. In the final screen, scroll down to Private keys and generate a new private key (this will download a certificate file, which you can open with any text editor)

📝 Tip: Save the App ID and the private key as environment variables, using GH_APP_ID and GH_APP_KEY respectively.

Connecting your Gitpod installation with your GitHub App

1. Verify that kubectx point to the correct context (your Gitpod installation)
2. Make sure your installation is up and running -- kubectl get pods should list the usual pods and display them in running.
3. Make sure the env vars GH_APP_ID and GH_APP_KEY are set with the values from above.
4. Run components/server/install-gh-app.sh

That's it 🎉 now your Gitpod installation should have a properly-configured GitHub App.

Note: If you redeploy your installation, simply run the above steps again.

Troubleshooting

1. If you need to remove the private key, you’ll need to delete the secret using kubectl.

   kubectl delete secret server-github-app-cert