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 step 1 on the Get started card, Connect GitHub. Click it and GitHub opens the install flow from the Latchkey app listing on GitHub. Pick the organization you want to monitor and confirm. When GitHub returns you to Latchkey, the installation is linked to your workspace and setup 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 the dashboard shows a "You'll need a GitHub organization" 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.

Create an organization and move your repo#

Only have a personal account? You do not need to abandon your existing repository. Create a free organization, move the repo into it, and reconnect. It takes a few minutes, and your history, issues, and stars come with it.

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 the Get started card picks up 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#