Setup

Using ngrok

You can use ngrok to expose a local port to the internet to accept incoming webhooks from Github. To do this, run the following:

task start-ngrok

Make note of the https URL as you will need it later.

Github App Creation

To create a Github app that can read from your repositories, navigate to your organization settings page (alternately, you can navigate to your personal settings page) and select Developer Settings in the sidebar. Go to Github Apps and select New Github App. You should use the following settings:

• Homepage URL: you can set this as https://hatchet.run (opens in a new tab), or some other domain for your organization.
• Callback URL: <protocol>://<your-domain>/api/v1/users/github-app/callback
• The Request user authorization (OAuth) during installation checkbox should be checked.
• Webhook URL: <protocol>://<your-https-ngrok-address>/api/v1/github/webhook
• Webhook secret: generate a random webhook secret for your domain, for example by running cat /dev/urandom | base64 | head -c 32. Make note of this secret, as you will need it later.
• Permissions:
  • Repository:
    • Checks (Read & write): required to write Github checks for each commit/PR.
    • Contents (Read): required for Hatchet to read files from the repository.
    • Metadata (Read-only): mandatory, required for Github apps that integrate with repositories.
    • Pull Requests (Read & write): required for Hatchet to add comments to Github PRs, and to create PRs.
    • Webhooks (Read & write): required for Hatchet to create a Github repository webhooks that notify the Hatchet instance when PRs are updated.
  • Account:
    • Email addresses (read-only): required for Hatchet to read your Github email address for authentication.

Creating a Secret and Private Key

After creating the Github App, create the following:

• In the "Client secrets" section, select Generate a new client secret. You will need this secret in the following section.
• In the "Private keys" section, download a new private key for your app. You will need this private key in the following section.

Private Keys and Environment Variables

After creating the private key, you can place it somewhere in your filesystem and set the SERVER_VCS_GITHUB_APP_SECRET_PATH environment variable to the path of the private key.

Make sure the following environment variables are set:

SERVER_VCS_KIND=github
SERVER_VCS_GITHUB_ENABLED=true
SERVER_VCS_GITHUB_APP_CLIENT_ID=<client-id>
SERVER_VCS_GITHUB_APP_CLIENT_SECRET=<client-secret>
SERVER_VCS_GITHUB_APP_NAME=<app-name>
SERVER_VCS_GITHUB_APP_WEBHOOK_SECRET=<webhook-secret>
SERVER_VCS_GITHUB_APP_WEBHOOK_URL=<webhook-url>
SERVER_VCS_GITHUB_APP_ID=<app-id>
SERVER_VCS_GITHUB_APP_SECRET_PATH=<path-to-pem-file>