GitHub

The GitHub Clerk

The Clerk is a specialist, the github preset. It holds three grants: github.read, github.write and shell.full, and owns the github skill. It works on every repository your token can reach, not only the workspace.

The main agent never reads an account itself. Questions about your GitHub go to the Clerk, so the account stays behind one specialist's grants.

Setup

1. Create a personal access token on GitHub under Settings, Developer settings, Personal access tokens. A fine-grained token is the better choice: pick the repositories, and give it Metadata, Contents, Issues and Pull requests read access. If you will turn writing on, make those read and write. A classic token with the repo scope also works, and is coarser.

2. Put it in your home's .env:

   GITHUB_ACCESS_TOKEN=github_pat_change-me
   

3. Install the github extra. In a checkout:

   uv sync --extra github
   

From the next session the Clerk is on the team. ivralo doctor has a github section that says what is in place. The token never reaches the model, the Python worker or the shell.

What it reads

Every claim cites its source: the repository, the number, the branch and path, the URL.

Writing, when you turn it on

With the defaults nothing on GitHub changes. IVRALO_GITHUB_WRITE=true adds creating and editing issues and comments, labels and assignees, opening pull requests and asking for reviews, and creating branches, files and repositories through the API.

Each of those pauses for your approval as a high-risk call: y approves it and Enter does not. None of them exists in a run nobody is watching, such as ivralo ask, a pipe or a schedule.

delete_repository is not in the toolkit ivralo builds, in any mode. No setting and no approval reaches it.

gh and git in the shell

Beyond the API, the Clerk uses gh and git through the shell: reading CI runs and their logs, reviewing a pull request, cloning, committing. gh uses your own login, set up once by hand:

gh auth login
gh auth setup-git

The second command lets git use the same credential over https. https is the way out: an ssh remote has no agent to reach, because SSH_AUTH_SOCK is not passed to the shell. ivralo never hands gh a token, and the commands that would print one are refused.

Every command is sorted before it runs:

The gh commands that ask are high risk in the dialog. A refusal is final: no answer in the dialog and no entry in permissions.json lifts it. With nobody to ask, every command that would ask is refused too. The full rules are on Shell commands.

The one push

The shell never pushes. The only push ivralo makes is open_pull_request, the tool of the git.push grant: it pushes a branch ivralo made and opens a draft pull request for it. The Code Engineer holds it, and so does the main agent, which holds the team's grants.

Before anything leaves the machine, every one of these must hold:

• the branch was made by ivralo, is not the default branch, and does not exist on the remote yet;
• every commit it would send was made by ivralo's own git identity in this session;
• no commit touches the repository's hooks;
• the folder is trusted, and origin is an https URL on the forge's host;
• the forge's host passes the egress policy.

It asks on every call, and no session-wide answer lifts that. With nobody to ask it is refused, except in server mode (IVRALO_MODE=server), which grants it unattended. It never merges, approves or enables auto-merge; merging is a person's act on GitHub.

ivralo's git identity is set by ivralo init --server with --git-name and --git-email, and is kept in gitconfig in the home, never in your own git config. The push signs in with GITHUB_ACCESS_TOKEN from the home's .env, or with the gh login when that was chosen at install. Give that token contents: write and pull requests: write on the repositories it works in, and nothing else. More is on Git and Draft pull requests.

The pull request card

When a turn opens a pull request, the session shows a card under the step that opened it: the number and title, the branches, whether it is open, a draft, merged or closed, and its checks with failures first. While checks are running, the card reads them again every 30 seconds, for at most 30 minutes. ivralo ask prints the card once, after the reply.

Settings

IVRALO_GITHUB_URL is read from the home's .env and the environment only, never from a repository's .ivralo/.env.