Skip to content

Latest commit

 

History

History
74 lines (46 loc) · 3.88 KB

README.md

File metadata and controls

74 lines (46 loc) · 3.88 KB
Raw

Towtruck

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.

Please review the High Level Design document if this is your first time in the project

Prerequisites

You must have nvm installed. It is available on brew. With nvm installed you should be able to run script/setup followed by script/server to run the application.

Configuration

Towtruck is set up as a GitHub App.

GitHub App settings

Using a test Github App

The first step is to register a new app as described here:

  • 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 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.

Once the app is registered, it should be installed to an account to allow Towtruck to track it. GitHub have instructions to do this here.

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.

Using the dxw Github App

This will use the live data from dxw's repos. Any testing to configuration should be performed using a personal test app first The environment variables are available here: https://github.com/organizations/dxw/settings/apps/dxw-towtruck. You may need to ask permission from an owner of the dxw organisation.

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. This can be found in the dxw-towtruck app settings.
  • PRIVATE_KEY: The private key used to sign access token requests. Towtruck expects this to be a .pem file generated by GitHub in the app settings and encoded using Base64. This can be generated from the .pem file by running script/encode-key <path-to-pem-file> in the terminal and copying the output.
  • CLIENT_ID: A unique alphanumeric ID assigned to the GitHub App. This can be found in the dxw-towtruck app settings
  • CLIENT_SECRET: A token used to authenticate API requests. These are generated by GitHub in the dxw-towtruck 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.

Seeding

Once all the other setup steps have been completed run script/seed or script/bootstrap --seed to seed the data. This will call the Github API which is rate limit so take care not to to run the script too often.