Expose Octokit app and Node middleware

This sets up the `App` instance and registers a generic set of webhooks
that can be used by the Node HTTP server as middleware.

.env.example

@@ -1 +1,5 @@
-GITHUB_PERSONAL_ACCESS_TOKEN=
+APP_ID=123456
+PRIVATE_KEY_PATH=/path/to/app.private-key.pem
+CLIENT_ID=SomeClientId123
+CLIENT_SECRET=secret
+WEBHOOK_SECRET=secret

README.md

@@ -1,2 +1,45 @@
 Towtruck is an application to aid maintenence of dxw's repos. 
 It aims to make it easier to keep on top of which repos need updates applying.
+
+
+## Configuration
+
+Towtruck is set up as a [GitHub App](https://docs.github.com/en/apps).
+
+
+### GitHub App settings
+
+The first step is to register a new app as described [here](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app):
+- For **9**, no callback URL is currently required, so this step can be skipped.
+- For **11**, no user authentication is currently required, so this step can be skipped.
+- Skip **12** as Towtruck does not use device flow authentication.
+- For **13** and **14**, there is no additional in-app setup performed by Towtruck, so these steps can be skipped.
+- Skip **15** as Towtruck does receive GitHub webhooks and should be configured to listen for them.
+- For **16**, the webhook URL should be configured to `https://<base Towtruck URL>/api/github/webhooks`.
+  Alternatively, for development, a [Smee.io](https://smee.io/) channel can be used.
+- For **17**, a strong, randomly-generated secret should be used.
+- For **18**, SSL verification should be used.
+- For **19**, see the **Permissions** section below for a list of required permissions.
+- For **20**, see the **Webhooks** section below for a list of required webhooks to listen to.
+- For **21**, **Any account** should be used in production when Towtruck is used to monitor multiple organisations.
+  Otherwise, **Only this account** should be used.
+
+
+#### Permissions
+
+Towtruck is still in early development so the exact set of needed permissions has not been finalised.
+
+
+#### Webhooks
+
+Towtruck is still in early development so the exact set of needed webhooks has not been finalised.
+
+
+### Environment variables
+
+In order for Towtruck to communicate with the GitHub API, it needs several pieces of information, configured through environment variables:
+- `APP_ID`: The unique numeric ID assigned to the GitHub App.
+- `PRIVATE_KEY_PATH`: The private key used to sign access token requests. Towtruck expects this to be an absolute path to a `.pem` file generated by GitHub in the app settings.
+- `CLIENT_ID`: A unique alphanumeric ID assigned to the GitHub App.
+- `CLIENT_SECRET`: A token used to authenticate API requests. These are generated by GitHub in the app settings.
+- `WEBHOOK_SECRET`: A user-defined secret used to authenticate GitHub to Towtruck for receiving webhooks. This must be exactly the same as it is entered in the app settings on GitHub.

octokitApp.js

@@ -0,0 +1,30 @@
+import { readFileSync } from "fs";
+import { App, createNodeMiddleware } from "@octokit/app";
+
+const APP_ID = process.env.APP_ID;
+const PRIVATE_KEY_PATH = process.env.PRIVATE_KEY_PATH;
+const CLIENT_ID = process.env.CLIENT_ID;
+const CLIENT_SECRET = process.env.CLIENT_SECRET;
+const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
+
+const privateKey = readFileSync(PRIVATE_KEY_PATH).toString();
+
+const app = new App({
+  appId: APP_ID,
+  privateKey,
+  oauth: {
+    clientId: CLIENT_ID,
+    clientSecret: CLIENT_SECRET,
+  },
+  webhooks: {
+    secret: WEBHOOK_SECRET,
+  },
+});
+
+app.webhooks.onAny(({ id, name, payload }) => {
+  console.log(name, "event received");
+});
+
+const middleware = createNodeMiddleware(app);
+
+export const OctokitApp = { app, middleware };