Documentation menu
Dashboard & analytics
Managed runners
Team & notifications
Billing & plans
Workflow files
Install the GitHub App
How the Latchkey GitHub App installation works, when you need an organization account, what permissions it uses, and how to fix a failed install.
In short
- Install from the Get started card's Connect GitHub step onto a GitHub organization; the installer becomes the workspace owner.
- A personal account connects and runs Latchkey CI; Latchkey on GH (Latchkey's managed runners in GitHub Actions) needs an organization.
- The app reads workflow runs and YAML and, for a repository you enable, its docs, CI config and file layout. It receives webhooks, writes Latchkey CI checks, opens the PRs you start and heal PRs on its own, and manages its runner group.
Latchkey connects to GitHub through a GitHub App. Webhooks, Latchkey CI runs and checks, the pull requests Latchkey opens, and Latchkey on GH runners all flow through it. A CLI job needs no code host at all. That makes the app the first thing to check when something from GitHub looks disconnected: if it is missing or sitting on the wrong organization, every one of those features 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.
Which account to install on#
Latchkey on GH needs the app installed on a GitHub organization. A personal (user) account connects as well and runs Latchkey CI: select the repository in the dashboard, then commit a workflow file under .latchkey/workflows/ and push; Workflow files covers the file. To use Latchkey on GH with a repository in a personal account, move the repository into an organization first, as the next section shows.
The install starts at Connect GitHub on the Get started card: GitHub opens the install flow, and you pick the account to install the app on. A personal account connects and runs Latchkey CI; Latchkey on GH needs an organization, so a repository in a personal account moves into one first. An organization runs Latchkey CI and Latchkey on GH, and installing on it needs the owner role. First, you install on your personal account, and you return to Latchkey. Next, a member of acme who is not an owner picks the organization: they ask an organization owner to install the app, then retry from onboarding. Last, an owner of acme installs it. Back in Latchkey, the installation links to a new workspace, whoever installed it becomes its owner, and setup continues to repository selection.
Create an organization and move your repo#
Want Latchkey on GH for a repository in your personal account? It needs an organization, and you do not need to abandon your existing repository: create a free organization, move the repo into it, and connect the organization. It takes a few minutes, and your history, issues, and stars come with it.
Go to github.com/
In the repository on GitHub, open Settings → General → Danger Zone → Transfer ownership, and transfer it to your new organization. Transferring keeps your commit history, issues, pull requests, and stars, and GitHub redirects the old URL so existing clones and links keep working. See Transferring a repository. If you would rather start clean, create a new repository directly inside the organization instead.
Back in Latchkey, click Connect GitHub on the Get started card and choose your organization. If this login already has a connected workspace, open the workspace menu in the sidebar, choose Add workspace, and connect the organization from the new workspace's Get started card: the organization gets a workspace of its own. One free trial per person: a second workspace is born without one and runs once it subscribes. The installation links to that workspace and setup continues to repository selection.
What the app can access#
In plain terms, the Latchkey app:
- Reads workflow run and job metadata (names, timings, statuses, runner labels). This is how a
latchkey-*job reaches a Latchkey runner and how Latchkey records the Latchkey on GH jobs it runs. The dashboard shows only the work Latchkey runs: these jobs, Latchkey CI runs and CLI jobs. Runs on other runners never reach it. - Reads your workflow files: the YAML under
.github/workflows/, so the AI can analyze it and propose concrete changes to the exact file an optimization PR would edit, and for Latchkey CI the files under.latchkey/workflows/, read at the commit that triggered the run and compiled into its plan. - Lets a Latchkey CI job clone the repository: the job's runner checks out the commit that triggered it, with a read-only token minted for that one job that expires within the hour.
- Writes Latchkey CI checks on your commits, Latchkey, Latchkey / plan, the advisory Latchkey / tests and one for each of a run's first 20 jobs, named for its workflow file and job, such as Latchkey / ci.yml / test, from the moment a repository enrolled for Latchkey CI commits its first workflow file under
.latchkey/workflows/. Before that first file, Latchkey writes no check on that repository, and a push that finds no workflow file shows no Latchkey CI run. The run of a tag push writes the same checks under names that carry its tag, such as Latchkey tag v1.4.0 and Latchkey tag v1.4.0 / ci.yml / test. When a push of the default branch starts a run at a commit less than four days after a push of another branch, a pull request or a merge group started one there, as at a fast-forward or when a merge queue lands, that run writes its checks under names that carry its branch, such as Latchkey branch main and Latchkey branch main / ci.yml / test, and Latchkey on that commit shows another run. Checks need the app's Checks permission. Until the account accepts it, no check is written, and once Latchkey has seen that it is missing, Settings, Code hosts shows the connection as Permissions not accepted, with Re-grant for an owner or admin. - Receives webhooks for pushes, pull requests and workflow events, so Latchkey learns of a commit or a queued job as it happens.
- Opens pull requests: the ones you start, by applying an AI Insight finding, migrating runners or approving a custom runner image, and heal PRs, which self-heal opens on its own when it finds a lasting fix for a failure in a job that ran on Latchkey (one small edit, to the workflow file the job ran from or to the engines field of
package.json). When self-heal keeps losing to the same failure on GitHub Actions, AI Insight shows its open heal PR, and an owner or admin can choose Stop proposing there to stop new heal PRs for that failure class in that workflow file on that repository, until it is undone under Declined fixes on the Self-healing tab of Settings. Every PR is for your review. Nothing is merged automatically, and no heal PR is opened for a pull request from a fork. - 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 else it reads: when you enable a repository, Latchkey indexes the repository's docs and CI config and scans its file layout, and when a step fails on a Latchkey runner, self-heal reads the step's output and can read the job's files. When a pull request runs on Latchkey CI, Latchkey also reads the list of files the pull request changes and keeps their paths for 90 days. Latchkey never calls GitHub's API for your secrets or variables. Your code is checked out only on the runner that runs your job, as on any CI runner, and that instance is destroyed when the job ends. If your security team wants the complete picture, including what each read is for, 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 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 and your own account's Settings, Applications 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: the Latchkey app asks for organization permissions, so GitHub lets only an organization owner install it. Ask an owner to install it, then retry from onboarding.
- Code hosts shows Permissions not accepted: the app is asking the account for permissions it has not accepted yet, and while the Checks permission is among them, Latchkey CI writes no check on that account's repositories. An owner or admin of the workspace clicks Re-grant in Settings, Code hosts, which opens the app's installation settings on GitHub, and an owner of that GitHub account accepts the permissions there. A connection that shows Reconnect instead was removed or holds a credential Latchkey can no longer use.
Common questions#
Q.01Who becomes the workspace owner?
The person who installs the GitHub App for a new workspace is linked as its owner. There is exactly one owner per workspace; the owner can later hand the workspace to another member with Transfer ownership. Details in Team and roles.
Q.02Can I install Latchkey on more than one organization?
Yes. Each installation gets its own workspace, with its own plan, team, repositories, and data. The workspace menu at the head of the sidebar moves between the workspaces you belong to. If you allow functional cookies, this browser remembers your last-used workspace the next time you sign in.
Q.03Do I have to be the GitHub organization owner to install?
Yes. The app asks for organization permissions, so GitHub lets only an organization owner install it. If you are not an owner, ask one to install it.
Q.04Does installing the app change anything in my repositories?
No. Installing it changes nothing in your repositories: there are no agents to install and no changes to your workflows until you choose to make them. After that, file changes reach your branches only through pull requests you merge. Latchkey commits only to new branches of its own and opens a pull request from each: one you start, or a heal PR that self-heal opens on its own. On Latchkey CI it also writes checks on your commits, and in an organization it manages its own runner group. See Security and GitHub permissions.