[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? :thinking:

[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](https://github.com/settings/apps/new) 2. Give your app a recognizable **name** (e.g. `Gitpod-`) 3. (**Homepage URL** can be your website or anything else) 4. Set the Post Installation **Setup URL** to `https:///api/apps/github/setup` (but replace `` with the hostname of your Gitpod installation) 5. Check **Redirect on update** 6. Set the **Webhook URL** to `https:///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](https://github.com/gitpod-io/gitpod/blob/main/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`. ```bash kubectl delete secret server-github-app-cert ```