Install the GitHub App

How the Latchkey GitHub App installation works, why it requires an organization account, what permissions it uses, and how to fix a failed install.

Latchkey connects to GitHub through a GitHub App. Installing it is the one-time setup step that everything else depends on: webhooks, analytics, AI recommendations, and managed runners all flow through the app. That also makes it the first thing to check when something looks disconnected: if the app is missing or sitting on the wrong organization, every downstream feature shows symptoms at once.

Installing during onboarding#

The normal path is onboarding step 1 ("Connect GitHub"). Click Authorize Latchkey and GitHub opens the installation page for the Latchkey app. Pick the organization you want to monitor and confirm. When GitHub returns you to Latchkey, the installation is linked to your workspace and onboarding continues to repository selection.

Organization accounts are required#

Latchkey supports GitHub organization accounts only. If the app is installed on a personal (user) account, Latchkey rejects it: the installation is automatically uninstalled from GitHub and onboarding shows a "personal account not supported" error so you can retry with an organization. If you only have a personal account, create a GitHub organization first (it is free) and transfer or create your repositories there.

What the app can access#

In plain terms, the Latchkey app:

• Reads workflow run and job metadata (names, timings, statuses, runner labels). This is the raw material for the cost, performance, and reliability dashboards.
• Reads your workflow YAML files under .github/workflows/, so the AI can analyze them and propose concrete changes to the exact file an optimization PR would edit.
• Receives webhooks for workflow events, so the dashboard stays current in real time. This is also why there is nothing to poll or refresh.
• Opens pull requests on your behalf only when you ask it to: applying an optimization recommendation, or a self-healing fix proposal. These PRs are always for your review; nothing is merged automatically, and pull requests from forks are never touched.
• Manages its own runner group in your organization so runs-on: latchkey-* jobs can be routed to managed runners. That is organization CI plumbing, not repository content.

What it does not do: Latchkey does not read your application source code beyond workflow files, and never reads your secrets or environment variable values. If your security team wants the complete picture, including runner isolation and data deletion, point them at Security and GitHub permissions; it is written to answer a security review directly.

If the installation goes wrong#

• Installed on the wrong account: if it was a personal account, Latchkey already removed the installation; just retry with the organization. If it was the wrong organization, uninstall the app from that organization on GitHub (Settings, GitHub Apps) and install it on the right one. To confirm where the app currently lives, check each organization's Settings, GitHub Apps page: Latchkey appears in the list wherever it is installed.
• Closed the tab mid-install: sign in again and Latchkey resumes onboarding where you left off; nothing needs to be undone first.
• No permission to install: installing a GitHub App on an organization requires owner or admin permissions. Ask an organization owner to either install the app or grant you admin rights, then retry from onboarding.

Common questions#