1. Sign in & install the GitHub App
You'll need a GitHub account. The whole flow takes about two minutes.
Sign in
- Go to app.kleio.build.
- Click Sign in with GitHub.
- GitHub asks you to authorize Kleio for read access to your basic profile, email addresses, and organization membership. Approve it. (This is the OAuth user-authorization step — it does not yet grant Kleio access to any repositories.)
- You land on the Kleio app, scoped to a personal workspace seeded from your GitHub username.
If you belong to one or more GitHub organizations, those will appear as candidate workspaces during onboarding. Pick the one you want this install to live in — you can install in additional orgs later.
Each Kleio workspace maps 1:1 to a GitHub owner (a user or an organization). All captures from repos under that owner roll up into the same workspace. The CLI auto-detects which workspace to use based on your git remote, so this mapping is the thing that makes "just cd into a repo and capture" work.
Install the GitHub App
After sign-in the app prompts you to install the Kleio GitHub App. You can also reach the install flow at any time from profile avatar › GitHub › + Add GitHub account, or directly via the GitHub Apps directory.
When GitHub asks which account to install on, pick the same owner you chose as your workspace. When it asks which repositories, you have two options:
- All repositories — recommended for personal accounts and small orgs. Kleio sees new repos as you create them.
- Only select repositories — recommended for large orgs or when you want to start with a single repo while you evaluate.
Either way, you can change the selection later (see Configure).
What permissions does the app request?
The full list (with the why for each one) is in github.com/kleio-build/kleio-github. Short version:
| Scope | Access | Used for |
|---|---|---|
| Email addresses | Read | Profile / login |
| Organization members | Read | Workspace discovery |
| Pull requests | Read & write | PR context comments, decision-traceability checks |
| Checks | Read & write | Check runs on PRs |
| Issues | Read | Linking captures to issues |
| Contents | Read | File context for captures |
| Metadata | Read | Required base permission |
Kleio's main app does not hold the GitHub App private key. A dedicated signer service mints scoped, short-lived installation tokens on demand. The integration is open source so you can audit exactly what we read and post back.
Verify the install
Back in the Kleio app, profile avatar › GitHub now shows the connected GitHub installation and the list of repositories Kleio has access to.
You're done with this page. Next: pick which repos Kleio watches and which event types become captures.