GitHub App setup

Set up a GitHub App to interact with your Geopoiesis scope

As a result of this step, you should have the following:

  • GitHub client ID;

  • GitHub client secret;

  • GitHub webhook secret;

  • GitHub app ID;

  • GitHub app key as a PEM file;

  • GitHub installation ID;

If you're using GitHub as source code repository provider, the recommended way is to set up a GitHub App. These are the officially recommended way to integrate with GitHub nowadays, because on top of authentication (provided by OAuth Apps) they provide temporary machine tokens to access the data with very granular permissions.

Setting up a GitHub App

First, please go to the Settings section of your GitHub organisation, and select the Developer settings > GitHub Apps menu item:

Then, click a button to register a new app. You will need to do a bit of setup. First, make sure you know the URL of your new Geopoiesis scope. In our example, we will use test.geopoiesis.io, and we will use HTTPS (recommended!) as a transport protocol.

In the first section, you will set up your OAuth authentication. Geopoiesis exposes the OAuth callback endpoint at the /oauth path:

Next, let's set up a webhook endpoint. Geopoiesis exposes the OAuth callback endpoint at the /webhooks path. You will need to generate a reasonably random string to pass as a webhook secret, which Geopoiesis can then use to ensure that the payload is sent by GitHub. Take note of that string, you will need to pass it to Geopoiesis later:

In the Permissions section, you will need to set up the following:

  • read-only for repository contents - for Geopoiesis to be able to pull the content of your repository;

  • read-only for repository metadata - for Geopoiesis to pull the metadata about your commits;

  • read-write for commit statuses - for Geopoiesis to be able to push commit statuses as checks to your PRs;

  • read-only for organization members - for Geopoiesis to be able to verify users' organization membership for authorization purposes;

Note: irrelevant permissions are omitted

In the last step, subscribe to Push events only, and set the app to only work for this account:

Once you click on the Create GitHub App button, your app will be created. You should be taken to the About section, which has some data you should take note of - you will need it later:

  • App ID;

  • Client ID;

  • Client secret;

You will also need to generate and save a private key, which is used by the GitHub App to generate short-lived authentication token. Keep this file safe - you will need it later:

Installing a GitHub App

Now that your app is set up, you will need to install it for your organization and repository. In order to do that, choose the Install App menu item from the list on the left hand side of your GitHub App settings page:

If you've set up your app correctly in the previous step, you should only be able to see a single account on the list:

Click Install, and in the next step choose to install the app on a single repository - the one that contains your Terraform config:

Once you've installed the application, make sure you take note of the installation ID in the URL. You will need it at a later stage.