Guides
Connect GitHub
Connect a GitHub token and Kelvar starts auditing your repositories on its own, then repeats the audit every 24 hours. This guide covers the read-only guard, the token it needs, what it reads, and the optional write-back application.
#Create a token
Create a GitHub personal access token for the account or organization whose repositories you want audited. Give it read access only.
For a fine-grained token, grant Read on the following repository permissions.
- Contents
- Pull requests
- Issues
- Actions
- Metadata
- Dependabot alerts, Secret scanning alerts and Code scanning alerts, if you want those alerts included
Select only the repositories you want Kelvar to see. A narrower token means a narrower audit and a smaller blast radius.
#Connect it
- Open Applications and choose GitHub (Read-Only Security Guard).
- Paste the token into GitHub access token.
- Select Connect.
Kelvar stores the token in your Home, and passes it to the guard process as an environment variable. It does not appear in prompts or in the ledger.
#What happens next
Connecting starts an audit without further input. The audit agent reads the repositories your token can see, records every confirmed issue as a finding, and the results appear on the Findings screen. The audit repeats every 24 hours, so new issues surface without anyone asking.
#What the guard can read
The guard exposes a fixed list of read operations. It has no operation that writes.
| Area | Operations |
|---|---|
| Code | get_file_contents, search_code, search_repositories |
| History | list_commits, get_commit |
| Pull requests | list_pull_requests, pull_request_read |
| Issues | list_issues, issue_read, search_issues |
| Workflows | actions_list, actions_get |
| Alerts | list_code_scanning_alerts, get_code_scanning_alert, list_dependabot_alerts, get_dependabot_alert, list_secret_scanning_alerts, get_secret_scanning_alert |
| Identity | get_me |
Because the guard is read-only by construction, a mistake in a prompt cannot push code, merge a pull request or change a setting.
#Opt in to write-back
To let Kelvar propose fixes as pull requests, connect the separate GitHub Write-Back (Pull Requests) application. It takes its own token, which needs write access to pull requests and contents on the repositories you choose.
Keeping the two applications apart means the token that audits your code never gains the power to change it. You can run Kelvar read-only indefinitely.
#Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| The audit finds nothing | The token cannot see the repositories | Check the repository selection on the token. |
| Alerts are missing | The token lacks alert permissions | Add the alert read permissions and reconnect. |
| Connect fails immediately | The token is invalid or expired | Create a new token and paste it again. |
To remove access, delete the token in GitHub. Kelvar stops being able to read the same moment.