Hermes Agent can work with GitHub through the same tools a developer would use: the gh CLI, GitHub webhooks, scheduled cron jobs, skills, and MCP servers when you need broader API access.
That makes GitHub one of the most useful Always-On Agents connectors. Hermes can turn raw ideas into issues, summarize repo activity, review pull requests, watch release feeds, and route implementation work back to Discord. The important part is not “give the agent GitHub.” The important part is giving Hermes the smallest GitHub authority that matches the workflow.
This guide is a simplified companion to the official Hermes Agent GitHub and webhook docs. Use the official docs as the source of truth, then use this page as the practical setup checklist.
Build an agent that keeps working after you close your laptop.
Start with the free setup checklist. It helps you avoid the usual traps: no place for state, secrets mixed with prompts, automations that send before you approve them, and logs you cannot debug later.
- VPS, Codex, Hermes, and Discord setup steps
- Approval gates before email, tickets, or posts change
- Reusable skills, scripts, and operating checklists
- A preorder path if you want the full walkthrough
What GitHub + Hermes connects
A basic Hermes GitHub setup connects these pieces:
For event-driven workflows, add the webhook gateway:
For scheduled workflows, use Hermes cron instead of webhooks:
The official Hermes PR review tutorial starts with scheduled polling because it works behind NAT and firewalls. The webhook tutorial is better when you have a public endpoint and want GitHub to push events immediately.
Who this setup is for
Use this setup if you want Hermes to:
- create or triage GitHub Issues from Discord notes, X bookmarks, support requests, or content ideas;
- review pull requests before a human reviewer spends time on them;
- summarize repo changes into daily standups;
- watch release notes and turn relevant changes into course/content tasks;
- keep implementation work in GitHub while Discord stays the command room.
Do not start with full repo mutation. Start read-only, then add write actions one workflow at a time.
Prerequisites
Before connecting Hermes to GitHub, have this ready:
| Requirement | Why it matters |
|---|---|
| Hermes Agent installed | The GitHub work runs through the normal Hermes agent loop. |
| A target repo or org | Start with one repo before adding org-wide scope. |
| GitHub CLI installed | Official tutorials use gh for PR lists, diffs, and comments. |
| GitHub auth on the Hermes host | Hermes can only do what the authenticated gh user or token can do. |
| A delivery surface | Discord, Telegram, or deliver: "local" for testing. |
| A safety policy | Decide which actions require review before comments, labels, commits, or merges. |
If you are building the full Always-On Agents stack, wire Discord first so GitHub results have a human control room.
Step 1: Install and authenticate GitHub CLI
Install gh on the machine where Hermes runs.
Authenticate:
For a private VPS, prefer a dedicated GitHub machine user or a fine-grained token with only the repo permissions required for the workflow. Do not reuse a personal all-powerful token just because it is convenient.
Verify the identity Hermes will inherit:
If those commands fail in your terminal, Hermes will not be able to use gh reliably either.
Step 2: Verify Hermes can read GitHub
Start Hermes in a normal chat session:
Then ask Hermes to run a read-only GitHub command:
A successful setup returns a small list of open pull requests or an empty list. Either result is fine. Authentication errors, rate-limit errors, or gh: command not found mean the GitHub layer is not ready.
For your own repo, test both issues and PRs:
Step 3: Choose the first GitHub workflow
Do not connect every GitHub action at once. Pick one workflow:
| Workflow | Best first implementation | Side-effect level |
|---|---|---|
| Issue intake | Create draft issues from approved Discord notes | Medium |
| PR review | Read PR diffs and post a review packet to Discord | Low |
| PR comments | Post review comments back to GitHub | High |
| Standup digest | Summarize issues, PRs, and CI changes | Low |
| Release monitoring | Watch trusted repos and emit source events | Low |
For most builders, the safest first GitHub workflow is a local or Discord-delivered PR review packet. It proves Hermes can read real repo state without posting comments or changing labels.
Step 4: Create a repeatable review or triage skill
The official PR review tutorial recommends using a skill so the review criteria persist across cron runs.
Create a local skill for your repo standards:
Then create ~/.hermes/skills/code-review/SKILL.md:
For issue triage, create a separate skill that defines labels, priority rules, acceptance criteria, and what must remain human-approved.
Step 5: Set up a scheduled GitHub review loop
Use cron when you want a reliable loop without exposing a public endpoint.
Example shape:
Verify the job exists:
Run it manually before trusting the schedule:
Start with --deliver local so output lands in ~/.hermes/cron/output/. Once the report format is useful, deliver to Discord or another configured messaging target.
Step 6: Add GitHub webhooks only when you need real-time triggers
Use webhooks when GitHub should push events to Hermes immediately.
The official webhook tutorial uses this route shape in ~/.hermes/config.yaml:
Start the gateway:
Smoke the local webhook service:
Expected shape:
When testing locally, keep deliver: log. Switch to github_comment only after the route, prompt, permissions, and review quality are safe.
Step 7: Register the webhook in GitHub
In the target GitHub repo:
- Go to Settings → Webhooks → Add webhook.
- Set Payload URL to your public Hermes webhook route.
- Set Content type to
application/json. - Set Secret to the same value as your Hermes route secret.
- Choose Let me select individual events.
- Select Pull requests for a PR review workflow.
- Save the webhook.
GitHub will send a ping event immediately. The official docs note that a ping event can be ignored if your route only accepts pull_request events.
Step 8: Keep comments and mutations approval-gated
Posting a PR comment is a public side effect inside the repo. Labeling, assigning, closing, merging, or pushing commits are even stronger side effects.
Use this progression:
- Read only: list issues, list PRs, fetch diffs.
- Draft only: deliver review packets to Discord or local output.
- Comment with approval: human approves before
gh pr comment. - Narrow automation: allow comments only on specific repos, labels, or branches.
- Broader mutations only after logs and rollback paths are proven.
For Always-On Agents, the durable pattern is not blind autonomy. It is a fast operator loop: collect, summarize, recommend, approve, then execute.
Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
gh: command not found | GitHub CLI is not installed on the Hermes host | Install gh, then retry from the same user account Hermes runs under. |
HTTP 401 or auth failure | Missing, expired, or shadowed GitHub token | Run gh auth status; check GH_TOKEN and GITHUB_TOKEN environment variables. |
| Hermes can read public repos but not private repos | Token lacks private repo access | Re-authenticate or use a fine-grained token scoped to the target repo. |
| Webhook route returns ignored | Event filter does not include the GitHub event | Add the event, or confirm the incoming header is pull_request. |
| Webhook health check fails | Gateway is not running or wrong port | Run hermes gateway and verify the configured port. |
| Review comment posts to the wrong PR | Template fields are wrong | Use {repository.full_name} and {number} from the GitHub payload. |
| Agent flags fake problems | Review prompt/skill is too vague | Add repo-specific conventions and require quoted evidence. |
| Agent follows instructions from a PR body | Prompt injection risk | Treat titles, descriptions, commits, and diffs as untrusted input. |
Security boundary notes
GitHub access should be narrower than your personal admin account.
Use these defaults:
- Start with one repo, not the whole org.
- Prefer fine-grained tokens or a dedicated GitHub machine user.
- Keep tokens in the OS keychain,
gh auth, or~/.hermes/.env; never commit them. - Do not paste real tokens into Discord, GitHub issues, screenshots, or docs.
- Use webhook HMAC secrets for public routes.
- Treat webhook payloads, PR titles, commit messages, and descriptions as attacker-controlled text.
- Use
deliver: logor Discord review packets before enablinggithub_comment. - Keep merge, close, delete, deploy, and production mutations human-approved until the workflow is boring.
Related BuildLeanSaaS pages
Use these next if you are building the full Always-On Agents repo loop:
- Hermes Agent Discord Setup
- Connect Hermes to Discord
- Connect Hermes to Google Workspace
- Plan a Content Release Watcher with Hermes
- Shape Up X Bookmarks into GitHub Work
- Prepare a VPS for Hermes
- Install Hermes/OpenClaw: A Private AI Agent Runtime on Your VPS
Official docs used
This page is a companion guide. The official Hermes Agent docs remain the canonical reference:
- Hermes Agent docs
- GitHub PR Review Agent tutorial
- Automated GitHub PR Comments with Webhooks
- Webhook messaging docs
- Bundled GitHub skills reference
- Full llms.txt docs bundle
Build an agent that keeps working after you close your laptop.
Start with the free setup checklist. It helps you avoid the usual traps: no place for state, secrets mixed with prompts, automations that send before you approve them, and logs you cannot debug later.
- VPS, Codex, Hermes, and Discord setup steps
- Approval gates before email, tickets, or posts change
- Reusable skills, scripts, and operating checklists
- A preorder path if you want the full walkthrough
Next Always-On Agents steps
If this GitHub setup is part of your operator stack, continue through the Always-On Agents path instead of treating it like a standalone GitHub bot:
- Connect Hermes to Discord so GitHub work has a private command room.
- Connect Hermes to Google Workspace when GitHub issues need to connect to email, docs, or client operations.
- Plan a Content Release Watcher with Hermes if your first repo workflow is release monitoring.
- Get the free Always-On Agents setup checklist before you add comment-posting or mutation permissions.