GitHub CLI¶
GitHub uses the broker's gh with each person's own sign-in. Agents use your
GitHub sign-in only for the work they do for you; an agent working for someone
else uses that person's sign-in, or none.
The broker keeps each person's sign-in in their own place: the token in the
credential store (Sealbox by default), and gh's settings in a private folder
per person under broker_credentials/users/. It does not read GitHub tokens
from environment variables: startup stops if GH_TOKEN, GITHUB_TOKEN,
GH_ENTERPRISE_TOKEN or GITHUB_ENTERPRISE_TOKEN is still set, and names
/link cli:github as the replacement. A request that works for nobody in
particular cannot use GitHub. GitHub sign-ins are personal: there is no team
GitHub account, so /link cli:github team only says so. The GitHub API tool
(http:github, for agents' web requests to api.github.com) is personal too:
link your own token with /link http:github; /link http:github team replies
"GitHub API uses only each person's own account."
In Web Chat, the authentication notice has an Open button. Select it to open the secure broker form in a new tab or window. The long authentication URL is hidden behind that link; credentials entered in the form are not sent to the agent. The link disappears when you dismiss it or refresh Web Chat. Run the command again if you need a new link. The CLI prints a URL you can open instead.
Browser Auth¶
This is the default: TeamLead's setup page and plain /link cli:github start
it (/link cli:github web does the same).
/link cli:github
The broker starts gh auth login --web and shows the browser/MFA steps. This
flow requests repo, read:org, gist, and read:project so GitHub Projects
v2 board reads work after login. The broker stores the resulting sign-in as
yours: in the credential store, or with file-backed broker state in your own
gh folder.
Select Open on the broker page to visit GitHub. The one-time code changes from Wait... to the code you need, and its copy button becomes available. The page checks progress in place, keeping the controls stable while you authorize. Broker CLI Output contains optional troubleshooting details.
For broad agent GitHub presence management:
/link cli:github web-all
Use web-all only when you intentionally want the broker to request its full
high-privilege GitHub OAuth scope profile.
Token Import¶
If you prefer to paste a personal access token, use:
/link cli:github token
Paste a token into the broker form. The broker checks it with GitHub and stores
it as yours. The token should include scopes matching the work you want the
agent to perform. For Projects v2 reads, include read:project.
Supported Broker Actions¶
auth.statusauth.logoutauth.login.credentialrepo.viewissue.listissue.view
Additional actions may be added to the broker as explicit allowlisted actions.
Verification¶
- Run
/link cli:github. - Complete GitHub browser/MFA auth.
- Run
/auth status; it asks GitHub whether your sign-in works. - Ask the agent to view a repository or list issues.
- For Projects v2 access, verify the token includes
read:project.
There is no shared broker gh sign-in to check by hand: each person's
sign-in is separate, and /auth status checks your own.
Commands through gh.exec¶
The broker checks every gh.exec command before it runs. Credential,
configuration, secret, key, extension and local-copy commands are refused
(auth, config, secret, ssh-key, extension, repo clone,
pr checkout, release create/upload/download). Options go after the full
command, and each short option and its value are separate arguments
(-X GET, not -XGET). File options (--body-file/-F, --notes-file,
--input) accept only - with the text sent as standard input, and field
values must not start with @, because both would read files on the broker
host. gh api accepts only GET and POST for now.
Logout¶
The agent can request github.auth.logout through the broker. This removes the
broker-owned local gh auth entry; it does not revoke the token server-side.