Cross-repo PR and release, from one control tower
PR Helper orchestrates real GitHub PR and deployment workflows with Lanes. Linear stages, independent merge routes, dynamic source rules, and convergence gates, e.g. feature/* + fix/* → dev → main. GitHub remains the authority for branch protection, reviews, checks, and deployments.
Lane workflow
The complete pipeline from PR intake to production rollback
- Configure Lane
Define stages, source rules (feature/*, fix/*), merge routes, convergence gates
- GitHub App install
Authorize per-repo, issue short-lived installation tokens
- PR intake
Webhooks update the Lane board in real time
- Gate decisions
domain.ts evaluates reviews/checks/mergeability from GitHub facts
- Stage advance
Dependent stages wait for predecessor merge + post-merge gates
- Deploy tracking
Deployment records, environment state, health checks
- AI PR drafts
24-hour drafts and streaming, session-only keys
- Web Push
Closed-tab delivery when SW + VAPID + reconciliation are ready
- Confirmed rollback
Explicit user action; dispatch with full audit events
Why PR Helper
Not a board, not a merge queue: accountability for the full release flow
GitHub is the authority
GitHub remains the authority for branch protection, reviews, checks, mergeability, Actions, and Environment protection. PR Helper never bypasses a GitHub rejection in UI state.
Lane orchestration
A Lane contains linear stages, independent merge routes, dynamic source rules, and convergence gates. Dependent stages need predecessor merge + post-merge gates; independent routes need not wait for earlier linear stages.
Real fact chain
Gate decisions are grounded in real GitHub Checks, Reviews, Mergeability, deployment records, and health checks, not Agent or UI self-report. Unexecuted verifications cannot be marked as passed.
Explicit production actions
Production merge and rollback are explicit user actions. No automatic production merge or rollback is added without an approved design. Rollback dispatch records full audit events.
Real-time + reconciliation
Webhooks provide real-time speed; scheduled reconciliation guarantees correctness. Supabase persists workflow and monitoring state; ordered migrations are the single source of truth for schema.
Credential safety
GitHub App secrets and short-lived installation tokens stay behind server modules under api/_lib/, never exposed to the browser. AI keys are session-only and not persisted before encryption is designed.
Compared to adjacent products
PR Helper doesn't compete with task board tools on tasks or deploy platforms on deploy speed
| Dimension | PR Helper | Task board tools | Merge queue tools | Deploy platforms | Manual |
|---|---|---|---|---|---|
| Unit managed | Cross-repo release workflow | Tasks/issues | PR merge order | Deploy hosting | Spreadsheets/IM |
| Platform-native | Yes, native app + webhook | Yes | Yes | Partial | No |
| Cross-repo Lane | Yes, linear/independent/convergence | Limited | No | No | Ad hoc |
| Convergence gate | Yes | No | No | No | Manual check |
| Gate decision source | Repo fact chain | Issue status | Queue status | Deploy status | Human judgment |
| Web Push delivery | Yes, closed-tab | Limited | No | Limited | No |
| Confirmed rollback | Explicit user action + audit | No | No | Instant rollback | Manual rollback |
| AI PR drafts | Yes, 24h + streaming | No | No | No | No |
Responsibility Boundary
Transparent split between GitHub authority and the orchestration layer
GitHub authority
- →Branch protection rulesets (source of truth)
- →Reviewer assignment and approval decisions
- →Actions, Checks, and Environment protection
- →Mergeability and merge method
- →Repository and GitHub App installation scope
- →Final decision on production merge and rollback
PR Helper is responsible for
- →Cross-repo Lane state orchestration and advance
- →Gate decisions evaluated from GitHub facts
- →Real-time Webhook ingestion and scheduled reconciliation
- →Closed-tab Web Push delivery
- →AI-generated PR drafts (session-only keys)
- →Deployment tracking, health checks, and audit events
- →Rollback dispatch only after explicit user confirmation
PR Helper guarantees process and evidence integrity, not a replacement for GitHub branch protection or human approval.
Product Constitution Excerpts
Core principles that constrain platform behavior
GitHub is the authority
GitHub remains the authority for branch protection, reviews, checks, mergeability, Actions, and Environment protection. Never bypass a GitHub rejection in UI state.
Explicit production actions
Production merge and rollback are explicit user actions. No automatic production merge or rollback is added without a separately approved product and safety design.
External facts over self-report
Gate decisions are grounded in real GitHub Checks, Reviews, Mergeability, deployment records, and health checks, not Agent or UI natural-language summaries.
Real-time + reconciliation
Webhooks provide real-time speed; scheduled reconciliation guarantees correctness. Both coexist; neither alone is sufficient.
Credentials never reach the browser
GitHub App secrets and installation tokens stay behind server modules under api/_lib/. AI keys are session-only and not persisted before encryption is designed.
Migrations are the truth
Database changes go only in new ordered migration files. No runtime DDL, and never edit an already-applied migration.
Frequently Asked Questions
Key questions about GitHub authority, rollback safety, and automation limits
What is PR Helper?
PR Helper is a GitHub-first PR / Release Control Tower that coordinates real pull-request and deployment workflows across repositories. A Lane can contain linear stages, independent merge routes, dynamic source rules, and convergence gates, e.g. feature/* + fix/* → dev → main. It is not a board or a merge queue; its minimum unit is the release workflow.
Does PR Helper bypass GitHub branch protection?
No. GitHub remains the authority for branch protection, reviews, checks, mergeability, Actions, and Environment protection. PR Helper never bypasses a GitHub rejection in UI state. Gate decisions are grounded in real GitHub Checks, Reviews, and Mergeability, not self-report.
Are production merge and rollback automatic?
No. Both production merge and rollback are explicit user actions. No automatic production merge or rollback is added without a separately approved product and safety design. Rollback dispatch executes only after explicit user confirmation, with full audit events recorded.
Where are GitHub credentials and installation tokens stored?
GitHub App secrets and short-lived installation tokens stay behind server modules under api/_lib/, never exposed to browser code. AI API keys are session-only and are not persisted server-side until encryption and key management are explicitly designed.
How are workflow and monitoring state persisted?
Workflows and monitoring state persist in Supabase Postgres via DATABASE_URL; ordered migrations live in db/migrations/ as the single source of truth for schema. Webhooks plus scheduled reconciliation ensure real-time speed and correctness; Web Push requires Service Worker, VAPID, subscription, and server reconciliation to all be in place.
What is a Lane? Can independent routes proceed without earlier stages?
A Lane is a project orchestration unit containing linear stages, independent merge routes, dynamic source rules, and convergence gates. A dependent stage advances only after all predecessor stages merge and their post-merge check/deployment gates succeed; independent routes may proceed without an earlier linear stage.
How is PR Helper different from task board tools, merge queue tools, or deploy platforms?
Task board tools manage tasks, merge queue tools manage PR merge ordering, and deploy platforms manage hosting. PR Helper manages the full cross-repo release workflow: Lanes orchestrate PR intake, gate decisions, stage advance, deployment tracking, health checks, and confirmed rollback, grounded in repository facts.
Turn cross-repo releases from chaos into control
Orchestrate real GitHub PRs, checks, deployments, and rollbacks with Lanes