Documentation menu
Dashboard & analytics
Managed runners
Team & notifications
Billing & plans
Workflow files
Security and GitHub permissions
Exactly what the Latchkey GitHub App can read and change, how runner infrastructure is isolated, and how deletion works.
In short
- Latchkey reads workflow runs/jobs and workflow files, the docs, CI config and file layout of a repository you enable, and a failed step's output and a job's files for self-heal. It never calls GitHub's API for your secrets.
- 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 changes files only on new
latchkey/branches, each with a pull request for you to review: the ones you start and the heal PRs self-heal opens on its own. On Latchkey CI it also writes checks on your commits. - Runners are single-job machines with no inbound access, destroyed after each job; deleting the workspace removes its data permanently.
This page describes what Latchkey can and cannot access, in plain terms, so your security review has a straight answer. It covers four things: what the GitHub App reads, when Latchkey writes to your repositories, how runner infrastructure is isolated, and how data deletion works.
What Latchkey reads, and what it never touches#
- Workflow run and job metadata: names, timings, statuses, runner labels and steps, and for a run its branch, commit, title, linked pull requests and the GitHub user who started it, for every run in a repository you enable, GitHub-hosted runs included
- Workflow files: the YAML under
.github/workflows/, and for Latchkey CI under.latchkey/workflows/ - Your repository at a Latchkey CI job's commit, cloned by that job's runner with a read-only token minted for the one job
- Your repository's docs and CI config, read from its default branch when you enable it and indexed for the knowledge base: root markdown files, markdown under
docs/,doc/anddocumentation/, workflow files, CODEOWNERS, issue and pull request templates, FUNDING.yml and other CI systems' config files. Their text goes to our embeddings provider. - Your repository's file layout, and up to 11 files a scan opens, read when you enable a repository and when a push to its analysis branch adds or removes a build-configuration file, to tell build configuration from application code. The folder names, build-configuration file names and opened files go to our AI model provider.
- Files in a job's checkout, or in the working tree a
latchkey runjob uploaded, read on the runner by self-heal to diagnose a failed step: at most four lookups a diagnosis and the first 8 KiB of a file. What it reads goes to our AI model provider and is kept in the heal record for 90 days. - A failed step's output, read on the runner by self-heal. When its AI stage runs, the end of each stream goes to our AI model provider, and the heal record keeps up to 1 MiB of each stream for 90 days. From a failed test step, Latchkey also keeps the names and files of failing tests and the step's test counts for 90 days. On Latchkey CI the names and files are kept to tell a flaky test from a broken one. Self-healing and your secrets below says how secrets in it are handled.
- The files a pull request changes: when a pull request runs on Latchkey CI, Latchkey reads from GitHub the list of files the pull request changes and keeps their paths, a renamed file under both names, with the pull request's number and commit, for 90 days. To check that list, Latchkey also reads the pull request itself. GitHub's answers can carry each file's changes and the pull request's title and description, and Latchkey keeps none of them.
- Repository metadata: the name, owner, visibility, description, language and default branch of each repository the app can access, read for Manage repository monitoring and not stored; for a repository you enable, also its branch names, read for picking the analysis branch, and details such as size, topics, license and fork status, which are stored with it; and on Latchkey CI, the default branch each push names, read to tell whether that push is the default branch's push
- For an organization, its GitHub plan and Actions minutes: both read when the app connects. Neither is read for a personal account.
- For an organization, its runners' names, labels, sizes, operating systems and whether each is available: self-hosted and GitHub-hosted, read when you preview or open a pull request that moves jobs to Latchkey runners, to pick the matching Latchkey size, and not stored. None of this is read for a personal account.
- Your GitHub secrets and variables, through GitHub's API (a secret a failed step prints is covered under Self-healing and your secrets below; the secrets a carry names reach the Latchkey vault only from inside a GitHub job you merge, as When Latchkey writes to your repositories shows)
- Issues and pull request discussions
The boundary is deliberate: nothing beyond the list on the left is requested. Run and job events are how Latchkey sees a job waiting for its runners, records and bills the jobs its runners serve, and notices failed runs for notifications and heal reports; workflow files are what the AI reads to propose optimizations and what Latchkey CI compiles into a run's plan, and the only kind of file an optimization PR edits; the clone is what a Latchkey CI job runs your commands on, and it is destroyed with the runner when the job ends; the docs and CI config are what self-heal searches in the knowledge base; the file layout and the files a scan opens mark which directories a fix may edit; the failed step's output and the job's files are what self-heal diagnoses, and the heal record keeps the output so a failure bundle can hand it to your coding agent, and on Latchkey CI the names of failing tests are kept to tell a flaky test from a broken one; the paths a pull request changes are how self-heal checks that a test it re-runs does not reach changed code, and how Latchkey CI works out which of the pull request's jobs no change reaches, without skipping any of them; repository metadata drives the repository list in Manage repository monitoring and the insight checks, and on Latchkey CI the default branch a push names is how Latchkey recognizes the default branch's push, which never joins a run that a push of another branch, a pull request or a merge group started at its commit; and your organization's GitHub plan and Actions minutes are recorded as the app reads them. Secrets you set in Latchkey for Latchkey CI are stored encrypted, and Latchkey decrypts one only when a running job asks for it for a step that names it. No dashboard, CLI or API-key request returns a value. A job's steps share one machine, so treat a secret as available to every step of the job that names it.
When Latchkey writes to your repositories#
Latchkey commits file changes only to new branches it creates, never to a branch of yours, and opens a pull request from each, in eight situations:
- An owner or admin applies an AI Insight finding that ships as a pull request: Latchkey opens a PR (branch
latchkey/insight-...) changing the workflow file. - Self-heal finds a lasting fix for a failure in a job that ran on Latchkey: it opens a heal PR on its own (branch
latchkey/heal-...), describing the root cause and one small edit, to the workflow file the job ran from or to the engines field ofpackage.json. A job started from the CLI never gets one. - You migrate runners from the Runners page or Settings: Latchkey opens a PR per repository (branch
latchkey/) changing themigrate-runners-... runs-on:labels in its workflow files. - You approve a custom runner image whose scan optimized workflows: after its build, Latchkey opens a PR (branch
latchkey/) moving those workflows onto that runner.optimized-workflows-... - An owner or admin carries a repository's secrets on the Secrets step of Move CI to Latchkey: Latchkey opens a PR (branch
latchkey/) adding one workflow,carry-secrets-... .github/. When you merge it, it runs once on GitHub and sends each secret the PR lists under Secrets, encrypted, to the Latchkey vault. A secret your workflow files read in jobs that name an environment is not sent for that environment: on GitHub such a job reads its environment's value when the environment has one, and the carry workflow names no environment. The PR lists each such secret under Set by hand with its environment, and an owner or admin sets it at that environment in Latchkey.workflows/ latchkey-carry-secrets.yml - Every secret a carry names has a value at each level its pipelines read it, carried or set by hand: Latchkey opens a second PR (branch
latchkey/remove-carry-...) that deletes that workflow. - An owner or admin opens the pull request on the Apply step of Move CI to Latchkey, or an agent calls the MCP
apply_migrationtool with a key that allows it: Latchkey opens a PR (branchlatchkey/) adding amigration-apply-... .latchkey/workflows/file for each pipeline that moves. - An owner or admin chooses Switch to Latchkey CI on the Migrate page: Latchkey opens a PR (branch
latchkey/, ormigration-switch-... latchkey/migration-switchfor a repository with no apply) removing the GitHub Actions workflow files the repository's Latchkey workflow files replace: each file an apply was made from, each file an owner or admin has named as replaced, and any file an earlier switch removed that is back. A file named only by an apply whose pull request is still open stays, and when none of the files is still in the repository, Latchkey opens no pull request.
| Write moment | What triggers it | What you see on GitHub |
|---|---|---|
| Optimization PR | An owner or admin applies a finding on the AI Insight page | A pull request titled "Latchkey insight: <what it does>" on a branch named latchkey/insight-... |
| Heal PR | Self-healing diagnoses a root cause that needs a durable fix in the repository | A pull request titled "Latchkey heal: <error summary>" on a latchkey/heal-... branch, describing what failed, why, and what the change does |
| Migration PR | You migrate runners from the Runners page or Settings | A pull request titled "chore(ci): migrate runners to Latchkey (<n> files)" on a latchkey/migrate-runners-... branch |
| Custom runner workflow PR | You approve a custom runner image whose scan optimized workflows | A pull request titled "Latchkey: Optimize workflows for <runner> runner" on a latchkey/optimized-workflows-... branch |
| Secrets carry PR | An owner or admin opens a carry on the Secrets step of Move CI to Latchkey | A pull request titled "Carry <n> secrets to Latchkey" on a latchkey/carry-secrets-... branch, adding .github/workflows/latchkey-carry-secrets.yml; merging it runs that workflow once on GitHub. If the carry is replaced by a newer one, or is still unmerged after 30 days, Latchkey closes that pull request and deletes its branch. A secret read in jobs that name an environment is listed under Set by hand and set at that environment |
| Carry removal PR | Every secret the carry names has a value at each level its pipelines read it, carried or set by hand | A pull request titled "Remove the Latchkey carry workflow" on a latchkey/remove-carry-... branch, deleting that workflow file |
| Apply PR | An owner or admin opens the pull request on the Apply step of Move CI to Latchkey, or an agent calls the MCP apply_migration tool | A pull request titled "Run CI on Latchkey CI" on a latchkey/migration-apply-... branch, adding a .latchkey/workflows/ file for each pipeline that moves. If the apply is replaced by a newer one, Latchkey closes that pull request and deletes its branch |
| Switch PR | An owner or admin chooses Switch to Latchkey CI on the Migrate page | A pull request titled "Run CI only on Latchkey CI" on a latchkey/migration-switch-... branch, or latchkey/migration-switch for a repository with no apply, removing the GitHub Actions workflow files your Latchkey workflow files replace. Once the repository is out of advisory mode, a run of it is live, though a pipeline in it can be on trial, and it is a trial run only when every pipeline it runs is on trial or an earlier attempt of that run was a trial run |
| Runner group management | Installing the app, so latchkey-* jobs can route to managed runners | The app manages its own runner group in your organization; no repository content changes |
| Latchkey CI checks | A Latchkey CI run on a commit, once the repository has a workflow file and the app holds the Checks permission | Finished checks named Latchkey, Latchkey / plan and Latchkey / tests (advisory, never required) on the commit, and a check for each of a run's first 20 jobs, named for its workflow file and job, such as Latchkey / ci.yml / test, which can show as queued and then in progress until its job ends. The run of a tag push writes them under names that carry its tag, such as Latchkey tag v1.4.0. 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 them under names that carry its branch, such as Latchkey branch main, and Latchkey on that commit shows another run; no repository content changes |
| Cancelled run | A latchkey-* job waits at least 10 minutes on a repository you enabled and then disabled | Latchkey cancels the whole run, GitHub-hosted jobs in it included; no repository content changes |
Every Latchkey PR is an ordinary pull request for your team to review, edit, or close. Latchkey never pushes to your branches directly and never merges anything, so if you never merge a Latchkey PR, none of your branches changes. No heal PR is opened for a pull request from a fork. On Latchkey CI, a pull request from a fork runs only when it comes from its author's own fork and the author has write access, or when a maintainer approves its commit. The runner group the app manages is organization CI plumbing, not repository content.
Runner isolation#
Managed runners execute your code, so their isolation model matters more than anything else on this page. Four properties work together:
- One job per runner. Every managed runner executes a single job and is destroyed afterward; nothing on it carries into another job or to another customer. Whatever a job writes, installs, or breaks disappears with the machine, unless the job saves it to a cache entry or uploads it as an artifact. What self-heal reads of a job's files stays in the heal record for 90 days.
- No inbound access. A runner reaches the internet through its own public address for outbound traffic only, and its security group admits no inbound connection: the runner reaches out to do its work, but nothing on the internet can initiate a connection to it.
- Hardened instance defaults, including enforced instance-metadata protections and encrypted disks.
- Registration is just-in-time on GitHub Actions runners: fresh runners register for exactly one job with single-use credentials, so there are no long-lived runner credentials to steal, and a credential is spent once its job completes. Latchkey CI runners never register with a forge.
Self-healing and your secrets#
When a step fails on a Latchkey runner, self-heal first classifies the failure on the runner, by pattern. When it needs a deeper diagnosis, its AI stage sends our AI model provider the end of the step's output (the last 4 KiB of each stream), the repository, branch and workflow names, and what it looks up: more log lines, the first 8 KiB of a job's file, the output of a retry it runs, or knowledge-base passages. A knowledge-base search also sends its search text, which can quote the error, to our embeddings provider. The heal record keeps the failed step's output (up to 1 MiB of each stream), the prompt and what the diagnosis read for 90 days. On GitHub Actions the output is captured before GitHub masks secrets. Before anything is sent or kept, the runner removes values a bash step hid with ::add-mask::, in their common encodings too, and any secret in a known format, such as a private key, an API token, a JWT, an authorization header or a password in a connection string. It also removes every secret the workflow file maps into the step's env:, and self-heal does not diagnose a step whose workflow file uses a secret any other way or cannot be read as it ran. A secret with no known format is in what is sent and kept as printed only when it reached your step some other way, such as through $GITHUB_ENV, and the step prints it without hiding it. Known secret patterns are removed again when a heal record is served. On Latchkey CI and latchkey run jobs, the secrets Latchkey delivered to the job, with their base64 and JSON-escaped forms, are masked on the runner before anything is sent or kept, but values you pass with --env are not. Self-heal is on for every new workspace, and an owner or admin can turn off Self-heal for this workspace on the Self-healing tab of Settings. The change reaches runners within about a minute, and a runner that cannot read the setting heals anyway. In-run fixes only touch the ephemeral runner; durable fixes only ever arrive as pull requests for review, and no heal PR is opened for a pull request from a fork. The full model is on Self-healing.
API keys and the MCP server#
If you connect an AI agent over MCP, the API key is the credential to reason about:
- Read-only by default. Keys can read CI failure and run data and your workspace's AI Insight findings; changing anything in Latchkey or GitHub is off by default, and a key can write only what was chosen for it at creation.
- Dispatch is opt-in per key. A key created with the Dispatch access also carries the
mcp:dispatchscope, letting the agent trigger GitHub Actionsworkflow_dispatchruns in your monitored repositories. Keys without that scope, including every key created before the option existed, cannot dispatch a GitHub Actions workflow. - Running jobs is opt-in per key. A key created with the CLI runner access carries the
jobs:runscope, letting its holder run one-off commands on billable Latchkey runners in your workspace. Under Customize access, Allow reading CLI job status and logs grantsjobs:readalone. - Setting secrets is opt-in per key. A key created with Allow setting workspace secrets carries the
secrets:writescope, letting its holder set or replace any workspace or repository secret in your workspace, for every repository, withlatchkey secrets set. An environment secret is set only in the dashboard, by an owner or admin. It cannot read a secret back. The CLI runner and secrets preset and the Full access preset carry it; Customize access adds it to any other level. - Approving runs is opt-in per key. A key created with Allow approving runs for an environment carries the
jobs:approvescope, letting its holder approve or reject a waiting run for any environment in your workspace through the Jobs API, which starts the jobs that name that environment or ends them without starting. It works only while the person who created the key is an owner or admin. The Approve runs preset and the Full access preset carry it; Customize access adds it to any other level. An agent that holds such a key and can also push to a repository can approve the runs of its own changes, with no other person deciding. - Opening migration pull requests is opt-in per key. A key created with Allow opening migration pull requests carries the
migration:applyscope, letting its holder open the pull request that adds a migration plan's Latchkey CI workflow files to a repository that is connected to Latchkey CI. A person still merges it. It works only while the person who created the key is an owner or admin. The Migration pull requests preset and the Full access preset carry it; Customize access adds it to any other level. - Starting Latchkey CI workflows is opt-in per key. A key created with Allow starting Latchkey CI workflows carries the
workflows:runscope, letting its holder start any Latchkey CI workflow file that declareson: workflow_dispatch, in any repository of the workspace connected to Latchkey CI, at any branch or tag and with any inputs, deploy workflows included. Its jobs run on billable Latchkey runners, and a job bound to an environment that needs an approval still waits for one, unless it is held in a trial run or a pipeline on trial, or its environment does not accept the run. The scope works only while the person who created the key is in the workspace. The Full access preset carries it; Customize access adds it to any other level. A key that also carriesjobs:approve, as a Full access key does, can approve the runs it starts while the person who created it is an owner or admin, with no other person deciding. - Re-running and cancelling Latchkey CI runs is opt-in per key. A key created with Allow re-running and cancelling Latchkey CI runs carries the
runs:controlscope, letting its holder re-run the jobs that did not pass of any Latchkey CI run in the workspace other than a preflight, deploy runs included, and cancel any run that has not finished. A re-run's jobs run on billable Latchkey runners, and a job bound to an environment that needs an approval waits for one, unless it is held in a trial run or a pipeline on trial, or its environment does not accept the run. The scope works only while the person who created the key is in the workspace. The Full access preset carries it; Customize access adds it to any other level. A key that also carriesjobs:approve, as a Full access key does, can approve the re-runs it makes while the person who created it is an owner or admin, with no other person deciding. - Workspace-scoped. The workspace is derived from the key itself, so a key can only ever see its own workspace's data.
- Shown once. The full key (it starts with
lk_live_) is displayed only at creation; after that the UI shows a placeholder. - Revocable. Revoke any key from Settings, API keys and agents, and it loses access within a minute. Revoked keys stay listed for audit.
Anyone holding a key can read your CI failure and run data, including the log tail of any completed job in a GitHub Actions run of a monitored repository, green runs included, the migration plan of any repository connected to Latchkey CI, and your workspace's AI Insight findings with the evidence behind them (estimated savings and money already spent, lists of unpinned actions, proposed workflow changes, the commit, run, job and step of the newest failure a trial saw only on Latchkey CI, and the batch or API key name, job count and spend behind a burst of jobs); a dispatch-enabled key can additionally re-run any manually dispatchable workflow in a monitored repository, a jobs-enabled key can run commands on billable runners, spending runner minutes, and read the logs of the workspace's Latchkey CI and CLI jobs, a key with workflows:run can start any Latchkey CI workflow that can be started on demand, deploy workflows included, a key with runs:control can re-run the jobs that did not pass of any Latchkey CI run other than a preflight, deploy runs included, or cancel any run that has not finished, a key with migration:apply can open the pull request that adds a migration plan's Latchkey CI workflow files to any repository connected to Latchkey CI, or close an earlier migration pull request of that repository, an approvals-enabled key can approve or reject a waiting run for any environment, which starts or ends the jobs that name it, and a secrets-enabled key can set or replace any workspace or repository secret your jobs read, though never read one back. Treat keys like passwords: store them in your agent configuration, not in a repository, enable writes only where you need them, and rotate any key that may have leaked.
Data handling#
- Data is encrypted in transit (TLS) and at rest.
- Analytics data is scoped to your workspace and isolated per organization: each workspace has its own plan, team, repositories, and data, and membership in one workspace never grants visibility into another.
- Self-healing diagnostics work on step logs within the runner; heal reports shown in your dashboard contain the diagnosis and action taken.
Deleting your data#
- Disable a repository: ingestion stops immediately; its knowledge base index and file layout scan are removed, and its GitHub Actions run records and AI history stay stored out of your dashboard. See Managing repositories.
- Cancel your subscription: access is blocked, but your data is retained so re-subscribing restores it.
- Delete the workspace (Settings, Account; owner only): charges the runner minutes run so far that month on a final invoice, permanently removes repositories, workflow data, and managed runner resources, and cancels billing.
- Delete your account: removes your Latchkey account and owned workspaces. Your GitHub repositories and workflows are never affected by any of these.
Q.01Can Latchkey read my secrets?
Not through GitHub's API: Latchkey never calls it for your secrets or variables. Two things are different. A Latchkey runner, like any runner, receives the secrets your job references when GitHub runs the job on it. And a secret with no known format that a failed step prints without hiding it with ::add-mask:: in a bash step is in the output self-heal reads, unless the workflow file maps it into that step's env:, which masks it; a step whose workflow file uses a secret any other way is not diagnosed. On GitHub Actions that output is captured before GitHub masks it, as Self-healing and your secrets above describes. Secrets you set in Latchkey for Latchkey CI are stored encrypted, decrypted only when a running job asks for one its step names, and never returned to the dashboard, the CLI or an API key. Everything Latchkey reads is in the list at the top of this page.
Q.02Does Latchkey write to my repositories?
Only on its own branches, and as checks. Latchkey commits file changes only to new latchkey/ branches and opens a pull request from each: the ones you start (an applied AI Insight finding, migrated runners, a custom runner's workflows, and the secrets carry, the apply and the switch of a move to Latchkey CI) and the heal PRs self-heal opens on its own. Nothing merges until you merge it, and nothing is pushed to a branch of yours. On Latchkey CI it also writes checks on your commits. The table under When Latchkey writes to your repositories lists every write.
Q.03What happens to my data if I delete my workspace?
It is removed permanently. Runners are single-job machines that are destroyed after each job, so nothing persists there between jobs, and deleting the workspace removes the stored analytics with it.