Among Hermes Agent’s ~78 bundled skills are several for GitHub — PR workflows, code review, issue triage, repo management — all gated behind one thing first: the agent actually being able to authenticate to GitHub. That’s handled by a dedicated github-auth skill.
How Detection Works
The skill checks four places, in this exact order, and stops at the first one that works:
ghCLI — ifgh auth statussucceeds, Hermes uses it for everything. This is the path of least setup: no token to generate or store at all.GITHUB_TOKENenvironment variable — used directly for API calls viacurlif set.~/.hermes/.env— aGITHUB_TOKEN=line in Hermes’s own config directory.- Git credential store —
~/.git-credentials, extracted as a last resort if nothing else is configured.
If none of these resolve, GitHub-dependent skills simply aren’t available — nothing crashes, they just can’t do anything that needs GitHub access.
Option A: Use the gh CLI (Simplest)
If you already have the GitHub CLI installed and logged in (gh auth login) on the box running Hermes, there’s nothing further to configure — the skill picks it up automatically as the first-choice method.
Option B: Set a Token Directly
If gh isn’t installed or authenticated, generate a personal access token. The skill’s own documentation recommends, for a classic PAT:
repo— full repository access: read, write, push, PRsworkflow— trigger and manage GitHub Actionsread:org— only if you’re working with organization repos- Expiration: 90 days as a reasonable default, rather than a token that never expires
If you’d rather scope it tighter, GitHub’s newer fine-grained tokens work just as well — limit repository access to only what Hermes needs, with Contents (read/write), Pull requests (read/write), and Issues (read/write) as the equivalent permissions.
Store it without it ever touching your shell history:
read -s -p "GitHub token: " GITHUB_TOKEN
echo
hermes config set GITHUB_TOKEN "$GITHUB_TOKEN"
unset GITHUB_TOKENThis writes it to ~/.hermes/.env. Restart the gateway for it to take effect:
hermes gateway restartVerifying It Worked, Without Printing the Token
Confirm the line exists without echoing the value:
grep -q '^GITHUB_TOKEN=.' ~/.hermes/.env \
&& echo "GitHub token configured" \
|| echo "GitHub token missing"Then confirm it actually authenticates:
set -a
source ~/.hermes/.env
set +a
curl -fsS \
-H "Authorization: Bearer $GITHUB_TOKEN" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/user |
python3 -c 'import json,sys; print("Authenticated as:", json.load(sys.stdin)["login"])'
unset GITHUB_TOKENIn practice, once this is wired up you don’t need to run these checks manually every time — you can just ask the agent directly (through whichever messaging channel you’ve connected) to run a read-only auth check. It’ll verify a token is present, call GitHub’s GET /user endpoint, and report back only the username and whether authentication succeeded — never the token itself.
Two Known Gotchas
hermes doctor Warns About a Missing Token Even With gh CLI Logged In
This is a documented false positive (issue #16115): the doctor check only looks for the GITHUB_TOKEN/GH_TOKEN environment variable, but the actual runtime correctly falls back to gh auth token when neither is set — the check just hasn’t caught up to that fallback logic. If you’re authenticated via gh and GitHub skills work fine in practice, the warning is cosmetic and safe to ignore. Setting GITHUB_TOKEN anyway will make the warning go away, at the cost of maintaining a token you didn’t strictly need.
GITHUB_TOKEN Not Visible Under the Docker Terminal Backend
If you’ve configured Hermes to use Docker as its terminal backend rather than local execution, a GITHUB_TOKEN set via .env or hermes config set may not be visible to commands the agent runs — because host environment variables aren’t automatically passed into the container. This is a known, open issue (#1436) with no official fix documented as of this writing. If GitHub commands fail specifically under the Docker backend despite a confirmed-working token, this mismatch is the likely cause, not a bad token.
Security Notes
- Prefer exporting the token as an environment variable or letting
ghmanage it over embedding it directly in commands — keeps it out of shell history and process listings. - If you use
git config credential.helper store, be aware it saves credentials to~/.git-credentialsin plaintext — a deliberate simplicity/security tradeoff the skill’s own docs acknowledge. - Set an expiration on any token you create; don’t generate one that never expires.
- GitHub no longer accepts password authentication for git operations — a personal access token is the password now, wherever a git prompt asks for one.
