Docs

Create a GitHub App

Last Light needs a GitHub App to act on your repositories. The App gives the bot its own identity (your-bot[bot] on comments and PRs), its own set of downscoped tokens, and per-repo installation control.

1. Create the app

  1. Go to github.com/settings/apps/new.
  2. Fill in the basics:
    • Name — your bot name. This is what appears on comments and PRs with a [bot] suffix.
    • Homepage URL — your repo URL is fine.
    • Webhook URL — https://your-host:8644/webhooks/github, or leave blank for now if you're deploying webhooks later.
    • Webhook secret — generate a random string. This becomes WEBHOOK_SECRET in .env.
  3. Uncheck Active under "Webhook" if you don't yet have a public URL. You can turn it back on after deploying.

2. Set permissions

Under Repository permissions, grant:

Permission Access Why
Contents Read & Write Clone repos, push branches, open PRs.
Issues Read & Write Triage, label, comment on issues.
Pull Requests Read & Write Review PRs, request changes, open PRs.
Checks Read & Write Post the last-light/review check on PRs and receive its "Re-run" requests.
Workflows Read & Write Merge or push PRs that touch .github/workflows/ — GitHub blocks the token otherwise. Needed for dependency PRs that bump GitHub Actions versions (e.g. actions/checkout), which the dependabot-pr-merge flow lands. Omit only if you never want the bot to touch Actions files.
Commit statuses (recommended) Read Read the classic commit statuses a repo's CI may post (CircleCI, Jenkins, other external CI) alongside check runs, so the auto-merge and fix gating see the full CI picture. Distinct from Checks above — GitHub exposes statuses and check runs as two permissions over two APIs, and one does not imply the other. Optional: without it Last Light judges CI on check runs alone and says so once in the log, rather than losing the CI signal entirely.
Actions (recommended) Read Read GitHub Actions job logs so the fix workflow can see why CI actually failed, rather than only check annotations. Distinct from Workflows above, which only governs writing files under .github/workflows/. Optional: without it Last Light still runs, falling back to check-run annotations — and it now says so explicitly in the prompt instead of degrading silently.
Metadata Read Default — required to see repo details.
Last Light mints downscoped installation tokens per workflow, so a triage run only sees read-only tokens even though the App itself has write permissions. See How it works for the full permission-profile story.

3. Subscribe to events

Under Subscribe to events, check:

  • Issues
  • Issue comment
  • Pull request
  • Check run — enables the "Re-run" button on the review check to re-trigger a review
  • Check suite — enables "Re-run all checks" to re-trigger a review
  • Pull request review (optional — currently ignored but will be used)

4. Install the app

  1. Click Create GitHub App.
  2. On the settings page, click Generate a private key and save the .pem file — you will need it in a moment.
  3. Note the App ID at the top of the settings page.
  4. In the left sidebar click Install App, then install it on the repositories you want Last Light to manage.

You can install the same app on several accounts — your personal account plus one or more organisations. Each install is separate and gets its own installation ID, but there is nothing to configure: Last Light discovers them all from the app's own credentials and picks the right one per repository owner. Just list repos from any of those accounts in managedRepos. If an owner appears there that the app was never installed on, the Config → Managed repos pane in the dashboard flags it.

5. Collect the three values

At this point you should have:

Value Env var
App IDGITHUB_APP_ID
Path to the .pem you savedGITHUB_APP_PRIVATE_KEY_PATH
Webhook secret you generatedWEBHOOK_SECRET

Keep the .pem file somewhere safe. In local dev, drop it into the project root and reference it with a relative path. In production, it lives inside secrets/ — see the Production deploy page.

← Previous Prerequisites