Connecting GitHub

Connect a personal GitHub account to Superprez and your decks live in your repos. You keep full ownership of the code, every commit becomes a deploy, and your AI tools (Cursor, ChatGPT, Claude, local terminals) work directly against the same repository Superprez serves. This page covers what it unlocks, how it's set up, and how the push-webhook auto-update loop works end-to-end.

Why connect your own GitHub?

Superprez can host repositories for you (using a Superprez-managed GitHub PAT), but connecting your own GitHub flips two important defaults:

You own the source. Repos are created under your user (or any org you have permission for) — not under a Superprez account. If you ever leave Superprez, the repo and its full git history stay with you, and your existing CI / branch protections / collaborators carry over.
Your existing tools just work. git clone, GitHub Desktop, Cursor, ChatGPT's GitHub connector, Claude Code, GitHub Actions, Dependabot, branch protections, PR reviews, issue tracking — none of it has to be re-configured. Whatever you do with a GitHub repo today still works.

Without personal GitHub in Settings (default zip hosting)

· Zip uploads create private GitHub repositories using workspace-managed credentials so Superengine can clone HTTPS.
· Updates: upload a new zip from the deck page or collaborate via share + modification zip—each lands as commits on main.
· You typically manage the deck inside Superprez (zip round-trip or dashboard)—there is no git push from your personal GitHub identity unless you switch hosting.
· Removing the deck can delete the GitHub repo on your behalf when hosting is Superprez-managed.
· Legal notices explain that GitHub's terms apply when source runs on GitHub without your own linked account—see Legal.

With personal GitHub connected

· Repos created under your account or selected org.
· git push from anywhere → Superprez auto-rebuilds the deck.
· Invite GitHub collaborators by email; they get repo access automatically.
· AI tools (Cursor, ChatGPT, Claude, etc.) operate on the same repo Superprez serves — no zip round-trip.

What connecting your GitHub unlocks

Auto-update on push. Superprez registers a push webhook on your repo. Every push to the tracked branch triggers Superengine check-for-update → update → (if the deck is live) restart. No manual zip upload, no "Run again" click. See how it works ↓
Connect existing repos. Choose Add presentation → Connect repo and point at any GitHub repo your account can access. Superengine clones it and deploys whatever's on the default branch.
Collaborators by email. When you Share a deck with someone using their email, Superprez invites them to the underlying GitHub repo too (with read or write, matching the share permission). They can clone and push directly.
Commits attributed to your GitHub user. When you've connected your personal PAT and choose My personal GitHub for uploads (or push from collaborators to your repositories), commits reflect your GitHub identity. Decks on Superprez-managed GitHub are updated with workspace credentials—not your personal login—until you migrate or reconnect under your PAT.
Source download for offline work. Two roles see a Download source (.zip) / Upload modified .zip panel on the deck page: collaborators you've shared with using Allow modification, and owners whose deck originated from a drop-code upload. Edit the zip anywhere (locally, with AI tools, etc.) and re-upload — Superprez publishes the new files as a single snapshot commit on the default branch (it rebuilds the tree from your zip rather than computing a textual diff), then triggers check-for-update + update on Superengine. Owners whose deck is linked to their own GitHub repo don't need this panel — they can git push directly.

Working with AI tools directly

With your GitHub connected, the deck repo becomes a normal repo to your AI assistants. Three patterns that work today:

Cursor / VS Code

git clone the repo, open in Cursor, ask the AI to refactor the deck, test locally with the framework's dev server, then push. Superprez rebuilds and the live URL refreshes within seconds.

ChatGPT / Claude with GitHub access

Both ChatGPT (Connectors) and Claude Code can read your private repos. Point them at the Superprez repo URL, ask for changes, and have them open a PR. Merging triggers the same auto-update path.

Local terminal + any LLM CLI

Use claude, aider, gh copilot, etc. against the cloned repo. As long as you ultimately push, Superprez picks it up.

Recommended dev loop

# 1. Clone (one time)
git clone git@github.com:<you>/<your-deck-repo>.git
cd <your-deck-repo>

# 2. Iterate with your AI of choice (Cursor, Claude, etc.)
#    Test locally with the deck's framework dev command, e.g.:
npm install
npm run dev

# 3. Ship — Superprez auto-rebuilds within seconds
git add -A
git commit -m "Tighten the hero, add slide 6"
git push origin main

How to connect your GitHub (5 min)

Superprez authenticates to GitHub with a Personal Access Token. Both PAT formats are accepted — the back-end validates the token by calling GET /user with Authorization: Bearer <token>, which works for both. Pick one of the two options below.

Create a Personal Access Token. You have two options:
Option A · Fine-grained PAT (recommended)
Open github.com/settings/personal-access-tokens/new. Scope it to "All repositories" or only the repos / org you'll use with Superprez. Token starts with github_pat_.
Repository permissions:
- Administration: Read & write — register webhooks.
- Contents: Read & write — push commits / import zips.
- Metadata: Read-only (auto).
- Webhooks: Read & write — push-update hook.
- (Optional) Pull requests: Read & write.
Option B · Classic PAT (legacy, simpler)
Open github.com/settings/tokens/new and create a token (classic). Token starts with ghp_. Scopes are repo-wide rather than per-repo, so review GitHub's PAT comparison before picking this path for organisation accounts.
Required scopes:
- repo — full repo CRUD + push (covers Contents read/write).
- admin:repo_hook — register and manage push webhooks.
- (Org-owned repos) read:org — to look the org up in API calls.
- (Optional) user:email — improves email-based collaborator lookup.
Paste the token in Superprez. Open Settings → GitHub, drop the token in the GitHub API key field (it accepts both github_pat_… and ghp_…), click Connect personal API key. Superprez validates the token, stores it encrypted, and shows Connected as <your-login>.
Create a deck under your GitHub. From the dashboard pick Add presentation → Connect repo (use an existing repo) or Add presentation → Drop code with the toggle set to personal GitHub (creates a fresh private repo under your account).
Confirm the webhook is active. Open the deck page; the GitHub auto-updates card should show a green Auto-update active pill. If it shows Not registered or Needs repair, click Register webhook.

Mockup · Settings → GitHub

GitHub

✓ Personal key: @your-handle

Connected. Repos can be created under your account; webhooks will be registered with this token.

Auto-update on push — full picture

The contract is straightforward: once a webhook is registered, every push to the repo's default branch triggers a sequence of API calls that ends with the running deck reflecting your new code. Here is exactly what happens:

You push commits → GitHub fires POST /api/webhooks/github on your Superprez instance, optionally signed with X-Hub-Signature-256 when you configured a secret in Settings.
The handler looks up the deck owner for that repository and verifies the HMAC against the owner’s saved webhook secret (optional — unsigned deliveries are accepted when the owner didn’t set one).
If the event is push, it looks up the presentation slug(s) tied to that repo (Superprez stores source_repo_full_name per deck).
For each slug, it calls Superengine in sequence:
- POST /app/<id>/check-for-update — flags that a newer commit exists.
- POST /app/<id>/update — actually does git fetch + checkout + rebuild.
- If the deck was live: stop → 750 ms → start, so the running process picks up the new code.
The webhook returns 200 to GitHub. Per-slug failures are logged in the Superprez back so GitHub doesn't retry the entire batch.

The webhook handler is at back/src/app/api/webhooks/github/route.ts and the orchestrator is checkPresentationForUpdate(slug) in back/src/server/services/presentations.ts.

Status panel & re-register

Open any presentation that has a GitHub repo linked. Below the GitHub repository card you'll see a new GitHub auto-updates panel that pings GitHub for the live state of the webhook and gives you a one-click Register / Re-register action.

Mockup · GitHub auto-updates panel (active)

GitHub auto-updates

✓ Auto-update active

Every git push to your-handle/your-deck-repo triggers Superengine check-for-update + update, then restarts the deck if it was live.

Hook ID: #48291 · Events: push · Last delivery: HTTP 200

Troubleshooting

Symptom	Most likely cause	Fix
Panel shows Server not configured.	The app's public HTTPS origin is missing or not reachable from the internet (common on local development).	Operators: set the public app URL in deployment configuration to an HTTPS origin GitHub can call, redeploy, then use Re-register. Presenters: optional webhook signing secret lives in Settings → GitHub.
Panel shows Missing GitHub token.	No personal PAT in Settings for this repo path, or Superprez-managed repos may not expose the same webhook controls. Zip-based updates still apply when offered on the deck page.	Add a Personal Access Token in Settings → GitHub — either a fine-grained PAT with Administration: write or a classic PAT with the `admin:repo_hook` scope.
Panel shows Not registered.	Webhook registration was skipped at deck creation (typically because the public URL was localhost at the time).	Click Register webhook. Superprez idempotently creates one now.
Panel shows Needs repair.	Hook exists but is disabled, missing the `push` event, or wrong content-type.	Click Re-register webhook. Superprez PATCHes the existing hook back to the desired state.
Last delivery shows HTTP 401.	The webhook secret stored on the GitHub side doesn’t match the value saved by the deck owner in Settings → GitHub → Webhook signing secret.	Update the secret in Settings (or clear it to disable signature checking), then click Re-register on this panel — Superprez will push the new secret to GitHub.
Pushed but the deck didn't refresh.	The push went to a non-default branch, or Superengine couldn't pull (private repo with no auth, build error, etc.).	Check Open repo webhooks on GitHub for the delivery log; check the back container logs for `[github-webhook]` entries with the slug and error message.

FAQ

Fine-grained PAT or classic PAT — which should I use?

Both work. Superprez talks to the REST API with Authorization: Bearer <token> and never inspects the token format. Pick fine-grained when you want per-repo scoping and short-lived expiry; pick classic when you need broader scopes (whole-account access, org-wide), accept the longer blast radius, and want fewer permission toggles. GitHub Apps are not yet supported as a first-class connector — that's on the roadmap.

What scopes are strictly required for auto-update?

Fine-grained: Administration: read & write (to register the webhook), Contents: read (so Superengine can clone), and Metadata: read. Contents: write is only needed if you want the drop-code zip upload from the Superprez UI to commit on your behalf. Classic: admin:repo_hook for the webhook plus repo (which already covers Contents read + write).

I pushed and the open Superprez page didn't refresh.

The running deck reflects the new code, but the Superprez page in your browser doesn't live-stream from GitHub yet. Reload the deck page (or its iframe) after a push to see the rebuild. Drop-code uploads inside the UI do auto-refresh because they originate from a click in your tab.

Does it support PRs / branches?

The webhook listens to push events. Whether Superengine actually rebuilds depends on the branch the deck app tracks (usually main). PR previews are not built unless you wire up your own GitHub Action that calls Superprez.

Is my PAT exposed to AI tools?

No. The PAT is stored encrypted in Superprez and only used by the back. AI tools authenticate to GitHub with their own credentials.