Skip to content
Latchkey home
Documentation menu

Quickstart: zero to dashboard

Sign in with GitHub, install the GitHub App, select repositories, and run your first job on Latchkey. Setup takes about five minutes.

In short

  1. Sign in with GitHub, install the app on your account or organization, select repositories: about 5 minutes, and the 30-day trial starts on its own.
  2. The dashboard fills as Latchkey runs your jobs. AI Insight's cost and reliability findings follow them; its security findings read your monitored repositories' .github/workflows/ files, so one can appear before your first job.
  3. Your first job: commit a workflow file under .latchkey/workflows/, or, in an organization, change one line to runs-on: latchkey-small.
app.latchkey.dev / acme / overview

Command & Control for a new acme workspace, its panels drawn as faint dashed outlines behind a Get started card. The card reads Let's run your first job and Your 30-day trial is already running. No credit card required, and offers two ways to set up, one above the other: Connect GitHub, with step 2 Select repositories (choose up to 10 repositories, starting with one is fine) dimmed and step 3 Add a workflow file below it, and Run a job from your terminal, with three commands. Connect GitHub is pressed and shows a loader while a card over the page reads Taking you to GitHub and GitHub shows exactly what Latchkey asks for. Choose Only select repositories to start with just one, and GitHub brings you back here. After the install on GitHub, a page reads Finishing GitHub setup and Connecting GitHub to your workspace. Back on Command & Control, step 1 is done and the Select repositories dialog opens: 0 / 10 repositories selected on the Launch plan and the line Choosing a repository doesn't start a build or change any code, with acme/api, acme/web and acme/worker all unticked. acme/api and then acme/web are ticked; the counter goes to 2 and the button reads Enable monitoring on 2 repositories. It is pressed, reads Enabling monitoring with a loader, and the dialog closes. A toast says Monitoring enabled on 2 repositories: Latchkey CI runs a repository once it has a workflow file under .latchkey/workflows/.

FIG. 1.2-ASigning in lands you on the Get started card. Connect GitHub sends you to GitHub to install the Latchkey app and brings you straight back to choose repositories; a new workspace's trial monitors up to 10.

This is the fastest path from nothing to your first job on Latchkey. Setup itself changes nothing in your repositories or workflows. Your first job comes from a workflow file you commit under .latchkey/workflows/, from the one-line runs-on: switch near the end, or from a job you run in your terminal.

01
Sign in
With GitHub; the 30-day trial starts automatically
02
Connect GitHub
Install the app on your GitHub organization
03
Select repos
Choose what Latchkey monitors
04
First job
Commit a workflow file under .latchkey/workflows/, or move one job to latchkey-small
Before you start
01
Sign in with GitHub

Go to latchkey.dev/sign-in and sign in with your GitHub account. Use the GitHub account that has access to the organization you want to monitor: the app install in the next step happens under this identity, and the person who installs the app becomes the workspace owner. You land on the dashboard's Get started card ("Let's run your first job"), and your 30-day trial is already running, no credit card required. If you get interrupted at any point, just sign in again; setup resumes where you left off.

02
Connect GitHub

Step 1 on the Get started card is Connect GitHub. Click it and Latchkey sends you to GitHub to install the app (a short interstitial explains what happens first). When GitHub asks where to install, choose your organization (a personal account runs Latchkey CI only). You need the owner role on the organization; if you are not an owner, ask one to install the app. What the app can and cannot access is covered in Install the GitHub App.

03
Select repositories to monitor

Step 2 on the Get started card, Select repositories, opens the repository picker, which lists your organization repositories with search and a visibility filter. Select the ones you want Latchkey to monitor; the counter shows how many your plan allows (10 on Launch, where every new workspace starts; 1 on Developer and 40 on Scale if you change plans later). Two things worth knowing while you choose: Latchkey CI and managed runners only serve monitored repositories, so include any repository you plan to run on Latchkey; and you can defer this with Skip for now in the picker, or I'll do this later on the Get started card, then finish later from the setup banner's Select repositories button or from Settings, Code hosts, Enrol repositories. Guidance on choosing under a plan limit is in Managing repositories.

04
Run your first job

After setup, a guided tour of the dashboard is offered; you can end it at any step and open it again from the Account and help menu. The Runs and Cost pages draw only the work Latchkey runs, so they stay empty until your first job: commit a workflow file under .latchkey/workflows/ and push (see Workflow files), move a job to a Latchkey runner (next step), or choose Run a job on the Runs page to run one from your terminal.

05
Optional: run a job on a Latchkey runner

Change one line in any workflow to try a managed self-healing runner. After you push, the job shows as queued on GitHub until a runner picks it up: about two seconds when a warm runner is already online, longer when a fresh runner cold-starts for you. The full walkthrough, including how to verify where the job ran, is in Run your first job.

.github/workflows/ci.yml
jobs:
  build:
    runs-on: latchkey-small
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test
06
Optional: invite your team

On every plan except Developer, open Team in the dashboard sidebar to invite teammates by email or shareable link (the Developer plan is for individual use, so invites are unavailable there). Invites grant the Admin or Member role. See Team and roles.

What to expect in the first hour#

Here is the typical sequence after you finish onboarding, so you know what is normal and what is worth a second look:

01
Minutes 0 to 5: setup
Sign in, connect GitHub, select repositories
02
First data lands
Each job Latchkey runs appears on Runs and in Cost; Latchkey CI runs also fill the pipeline figures on Command & Control and Performance
03
AI Insight comes online
Detectors run nightly, hourly for spend, and once about 2 minutes after you enable a repository; cost and reliability findings follow the runs Latchkey serves, and a finding read from your workflow files under .github/, such as unpinned actions, can appear within minutes
04
Live from here on
Command & Control refreshes its pipeline figures on its own every 15 seconds while a Latchkey CI run is in progress and every 2 minutes otherwise; Performance and Cost refresh every 2 minutes

Where to go from here#

Q.01How long does Latchkey take to set up?

About five minutes: sign in with GitHub, install the app on your organization, and select repositories. The 30-day trial starts on its own, with no separate step.

Q.02How long before I see data in the dashboard?

As soon as Latchkey runs your first job. The dashboard draws only the work Latchkey runs (Latchkey CI runs, CLI jobs and latchkey-* jobs), never runs on other runners. AI Insight's cost and reliability findings follow the work Latchkey runs; a finding read from your .github/workflows/ files, such as unpinned actions, can appear within minutes.

Q.03How do I run my first job on a Latchkey runner?

Change one line in the workflow: replace the value of runs-on with latchkey-small. Your steps, actions, secrets, services and matrix stay exactly as they are, and GitHub-hosted labels keep working in the same workflow, so you can migrate one job at a time.