Skip to content
KylthDOCS

GitHub integration

Connect your own GitHub App so Kylth can read repositories, deploy migrations and build pull request previews.

Kylth can read a project’s repository to deploy its Supabase migrations and to build previews for pull requests. It connects as a GitHub App that you create and own, on your own GitHub account or organisation.

Once it’s connected, Migrations from GitHub explains what happens on each push.

Kylth never acts as a GitHub user, and never asks for a personal access token. It uses the App's own credentials, which only reach the repositories you install the App on.

Create the App

In GitHub, go to Settings → Developer settings → GitHub Apps → New GitHub App.

Field Value
GitHub App name Anything, for example Kylth. GitHub makes a URL from it, called the App’s slug.
Homepage URL Your dashboard, for example https://app.example.com/
Setup URL https://app.example.com/github/setup
Redirect on update Tick it
Webhook → Active Tick it
Webhook URL https://app.example.com/webhooks/github
Webhook secret Generate a long random string and keep a copy

Kylth shows the exact Setup URL for your installation under Settings → GitHub, so you can copy it rather than assembling it by hand.

Permissions

Under Repository permissions, set:

  • Contents: Read-only. Migrations and function code are read from the repository.
  • Metadata: Read-only. GitHub requires it alongside Contents.

Nothing else. Kylth only ever reads.

Events

Under Subscribe to events, tick:

  • Push, which is what triggers a migration deployment.
  • Pull request, if you want preview environments for pull requests.

Keep it private

Under Where can this GitHub App be installed?, choose Only on this account, unless you have a reason to let others install it.

Give Kylth the App’s details

  1. On the App’s page, note the App ID, and the slug from its public link (https://github.com/apps/<slug>).
  2. Select Generate a private key. GitHub downloads a .pem file. It’s shown once.
  3. In Kylth, open Settings → GitHub → Configure App, and enter the App ID, the slug, the private key and the webhook secret.

Kylth encrypts the private key and the webhook secret before storing them, and never shows either again.

Without the webhook secret, Kylth answers every delivery from GitHub with 404 and migrations never deploy. It’s not optional.

Connect a repository

  1. Open a project and select Connect GitHub. Kylth sends you to GitHub to choose the account and repositories to install the App on. To add a second account later, use Connect a different account.
  2. GitHub returns you to Kylth, which records the installation.
  3. Map the project to a repository and branch.

Installing the App on an account authorises Kylth to read that account’s selected repositories, so it’s restricted to organisation administrators.

What Kylth reads

Only these, all read-only:

  • the repositories the installation grants
  • branches, and the commit a branch points at
  • files under the project’s migrations and functions folders

Troubleshooting

Migrations don’t deploy after a push

  • Check: in the App’s Advanced tab on GitHub, look at Recent Deliveries. A 404 means the webhook secret in Kylth doesn’t match the App’s, or none is set. A 401 means the signature didn’t verify, which is the same mismatch.
  • Fix: set the same secret in both places, under Settings → GitHub → Configure App.

GitHub can’t reach the webhook

  • Cause: the webhook URL must be reachable from the internet over HTTPS, like the rest of your dashboard.
  • Check: the delivery’s response in Recent Deliveries.

The install returns to a page that says the state didn’t match

  • Cause: the return leg is tied to the browser session that started it, and it expires.
  • Fix: start again from the project’s Connect button, in the same browser.