{}Agent Hub

GitHub App · opens PRs, never pushes to main

Agent Hub Sync

The generator on the homepage gives you a great file once. This keeps it that way — a GitHub App that watches your repo and opens a pull request the moment your stack changes or Agent Hub ships new guardrails, so your AI coding agent's rules never quietly fall behind.

On every push

Re-scans your manifests. Added a new framework or database? The next sync notices and opens a PR adding that stack's guardrails — you never have to remember to regenerate by hand.

Once a day

Checks whether Agent Hub's own template content has moved to a new version since your last sync — even for a repo that hasn't been touched in weeks. See the changelog for what that covers.

Two prerequisites before you start:

  • Deploy this project first. GitHub validates the webhook URL when you create the App, so it needs to be a real, publicly reachable domain — NEXT_PUBLIC_SITE_URL can't be localhost. Run step 1 below from your deployed site, after setting that env var to your real domain.
  • Set up Redis first too. UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN (a free database from the Vercel Marketplace or upstash.com) — Sync has no in-memory fallback like /admin's analytics does. Skip this and everything below will appear to work — the App installs fine, GitHub shows green checkmarks — while every actual sync silently does nothing.

Set it up

  1. 1. Create your own instance of the App. Agent Hub Sync isn't a single shared App you install from a marketplace listing — running your own instance means the sync bot only ever has the exact GitHub permissions you granted it, on the exact repos you chose, with no shared credentials between different users of this project.
    Create your GitHub App →
  2. 2. Paste the resulting credentials into your deployment's env vars and redeploy. The page after step 1 lays this out as four copy buttons plus a live check of whether Redis and CRON_SECRET are already set — it won't let you miss either one. Same .env pattern as everything else in this project (see the README's Environment variables section).
  3. 3. Install it on your repositories, after the redeploy finishes. The same page gives you the install link once your App exists — wait for step 2's redeploy to actually complete before clicking it, or the first webhook delivery hits the old build.
  4. 4. Verify it worked. Check /admin/sync (behind your admin login) — the repo should show up with a status within moments. If it doesn't, the troubleshooting section below almost certainly has it.

Installing on someone else's hosted instance?

If you clicked an install link for an App you didn't create yourself — a hosted instance someone else runs — skip all of the above. Manage your own repos and config at /dashboard, signed in with the same GitHub account you installed with. You'll only ever see your own repos there, never anyone else's.

Questions

What does it actually do?+

It watches your default branch. On every push, it re-checks your manifests (package.json, requirements.txt, etc.) for stack changes, and separately, once a day, it checks whether Agent Hub's own guardrail content has moved to a new version. Either one can trigger a pull request with the updated files — never a direct push to your default branch.

Does it ever push directly to my main branch?+

No. It only ever commits to one dedicated branch it owns (agent-hub-sync) and opens or updates a pull request from that branch. You review and merge it like any other PR.

What if I've customized the generated files?+

If nothing has changed since the last sync, it does nothing — the check is a real content diff, not a blind overwrite. If something has changed, the PR shows exactly that diff against what's currently committed, including your edits, so you review and merge (or reject) it consciously rather than losing changes silently.

Can I configure which stacks, tools or custom rules it uses?+

Out of the box it starts from a zero-config default: auto-detected stacks, Combined mode, and GitHub Copilot + Claude Code + Cursor. For anything more specific, edit the files directly in the PR it opens — your edits are respected on every subsequent sync as long as nothing upstream has changed for that file.

Is my repo's code ever sent to a server?+

Only what's needed to detect your stack: the contents of a handful of root-level manifest files (package.json, requirements.txt, go.mod, etc.), read directly from GitHub's API using the permissions you grant on install. Nothing is stored beyond the small config needed to run the next sync (which repo, which stacks, which version was last synced).

Troubleshooting

Real failure modes hit while building this feature, not guesses — if a sync isn't doing what you expect, one of these is very likely why.

Nothing seems to happen after installing the App, or after a push.

Check your deployment's function logs (Vercel: Project → Logs), filtered to "agent-hub-sync" — every run logs its outcome there even when nothing visible happens. "no-manifest-signal" means no supported manifest file (package.json, requirements.txt, etc.) was found at the repo root. If you see no agent-hub-sync log lines at all, check the App's Advanced tab → Recent Deliveries on GitHub to confirm the webhook is actually reaching your deployment.

A sync ran (the logs say pr-opened) but I can't find the PR.

GitHub's global Pull Requests inbox filters to PRs that "involve you" by some notion GitHub applies internally, and can miss one opened by the bot on a repo you own. Check that repo's own Pull Requests tab directly, not the cross-repo inbox.

Pushing to main did nothing, but pushing to another branch triggered a sync.

Sync only reacts to pushes on the repository's actual GitHub-configured default branch — whatever it's set to, not necessarily the literal name "main". Check Settings → Branches on the repo in question. (A push to a branch with its own open PR can also trigger a comment from Vercel's own preview-deployment bot, which is unrelated to Agent Hub Sync entirely — easy to conflate the two if both fire around the same time.)

A sync fails with "Resource not accessible by integration" pointing at the git/trees API.

The "Include CI enforcement check" option writes a GitHub Actions workflow file, which needs the App's separate "Workflows" permission — "Contents" access alone isn't enough. Apps created through the flow below request it automatically now; if your App predates that, add it under the App's Permissions & webhooks settings on GitHub, save, then accept the updated permissions for the installation (Settings → Installations → Configure). Turning the CI check option off avoids this entirely.

Right after creating the App, the redirect lands on a 404 (NOT_FOUND) page.

Almost always NEXT_PUBLIC_SITE_URL pointing at a different domain than what's actually deployed — double-check it matches your real production URL exactly (your Vercel project's assigned domain, not a placeholder), then redo the setup flow from that exact URL.

I closed the sync branch's PR without merging, and the next change opened a new PR instead of reopening it.

Expected, not a bug — Sync only ever updates a currently open PR. Closing one and then pushing another change opens a fresh PR from the same branch rather than reopening the old one.