GitHub OAuth app setup

This page describes the (not recommended) GitHub OAuth integration

This approach to GitHub integration is deprecated and may be removed at some point. It's highly recommended to set up a GitHub App instead.

If you haven't done that before, GitHub offers an excellent introduction to building OAuth apps and you will probably want to read it first. When registering a new app, you will be greeted with a screen like this:

The only really relevant bit is the Authorization callback URL. The example below assumes that you will be running Geopoiesis on localhost and exposing the HTTP interface on port 1983, which what Geopoiesis does by default, unless a PORT environment variable is provided with a different value. Make sure that the callback URL ends with /oauth, otherwise you'll end up with a redirect loop.

The above example uses unencrypted HTTP protocol because you're making the connection to your local machine. However, if you do that on the Internet, you're going to have a bad time. Please always use HTTPS for non-local traffic.

Once you click on the Register application button, you will be redirected to a screen like this:

Make note of your Client ID and Client Secret, as you will need to pass them as GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET environment variables in the App configuration step.

Source code access

Unfortunately, an OAuth app does not automatically grant access to the source code. In order to grant Geopoiesis access to a GiHub repository, you will need to generate an API token. First, navigate to the Personal Access Tokens section of GitHub web UI and press the Generate new token button. When prompted for the scope of your token, choose repo:

After you approve the choice, a new token will be generated for you:

Make note of this value as you will need to pass it as GITHUB_ACCESS_TOKEN environment variable in the App configuration step.

Note that if your GitHub organization uses Single sign-on you will need to whitelist your token for SSO. In order to do that, just click on the little SSO link next to the Delete button.

The token you generated above gives its holder full access to your GitHub repositories - both public and private. Beyond testing phase, you will probably want to limit the blast radius by creating a service account for Geopoiesis and similar tools, with access to only a few selected repositories.

Webhook secret

The basic app setup does not involve setting up VCS provider webhooks, but it's still a good idea to think about them at this stage. For now, let's come up with a reasonably random (or at least hard to guess) string, which we can use to identify incoming requests. Make note of that string as you will need to pass it as GITHUB_WEBHOOK_SECRET environment variable in the App configuration step.