Connecting GitHub

REVETOOL connects to GitHub at two levels: workspace OAuth (to sync PRs and issues) and per-project webhook (to receive real-time updates when PRs open or update).

Step 1 — Workspace OAuth

1. Open Workspace settings → Connectors.
2. Click Connect GitHub.
3. Review scopes on GitHub consent screen.
4. Click Authorize.
5. You are redirected back. REVETOOL stores your encrypted token.

Step 2 — Link a repo to a project

OAuth alone is not enough. You also link specific repos to specific projects.

1. Open your project → Connectors.
2. In the GitHub section, click Link a repo.
3. Pick from your authorized repos.
4. Click Link. REVETOOL stores the mapping in project_github_repos (M:N relation).

Step 3 — Set up the webhook

For real-time PR sync (and auto-staging-screens), you need to install a webhook on each linked repo.

1. On the linked repo card, click Setup webhook.
2. REVETOOL displays the webhook URL + the HMAC secret (1 secret per project for isolation).
3. Copy both to GitHub repo → Settings → Webhooks → Add webhook.
4. Set Content-Type to application/json.
5. Subscribe to events: pull_request, pull_request_review.
6. Save. GitHub will send a ping event to verify.

What happens when a PR opens

1. GitHub sends webhook to /api/github/webhook/[projectId].
2. REVETOOL verifies HMAC signature.
3. Extracts [US-XX] pattern from PR title.
4. Finds the matching ticket in the project.
5. For each concept linked to that ticket, creates a staging screen with env_kind=staging + label PR #N.
6. If Vercel PAT is also connected, fetches the preview URL and sets it on the staging screen.

Step 4 — Import existing issues as backlog

On a linked repo card, click Import issues. REVETOOL fetches open issues (skipping PRs via the pull_request property) and creates backlog tickets.

• GitHub labels → backlog type/priority (mapping configurable per project).
• UPSERT batch idempotent on (project_id, title) — re-import is safe.
• Linked issue URL stored so you can jump back to GitHub.

AI code context

When you run AI analysis with the Code flag enabled, REVETOOL fetches code context from your linked repo.

1. Extract keywords from the screen path (basename + parents).
2. Search GitHub for files matching those keywords.
3. Score each file (weighted match).
4. Pick top 3 files, truncate to 200 lines / 5KB each.
5. Inject into AI prompt as code context.

Troubleshooting

Webhook signature invalid

Most likely a secret mismatch. Re-generate the webhook in REVETOOL settings, update on GitHub side. The HMAC secret is per-project for isolation — workspace A's secret won't match project B's endpoint.

PR opened but no staging screen created

Check the PR title — it must contain [US-XX] or similar pattern matching a ticket. Also check that the ticket is linked to at least one concept with at least one variant.