Repository navigation
feat(hub): import GitHub Actions Builds - #300
Merged
Merged
Conversation
Restore skip-build and output-directory from #179 so repositories can use their own build command, npm registry, and output folder. Upload the replica-build-v1 dist before any Chromium or screenshot work, and add a screenshots sub-action that publishes replica-screenshots-v1 bound to the dist digest. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Import replica-build-v1 artifacts from Replica workflow runs as soon as the dist job completes, with idempotent write-once storage, and attach replica-screenshots-v1 later only when its dist digest matches. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Provide a two-job prototype workflow and exercise the artifact handoff across jobs in CI. Keep inline screenshots compatible and document when Hub can start importing the dist. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Complete Builds only while the owning attempt holds the row, align Hub size limits with the build action, keep the current Build on reused commits, replace finished import jobs on redelivery, keep failed attempts failed, and request the workflow_job App event. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The publish action packages an existing output directory and uploads replica-build-v1 without npm, Docker, or a browser, so prototype repositories can use their own build and import the dist before a dependent screenshots job runs. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Actions CI now builds the fixture with its own build, publishes it with the publish action, and captures screenshots in a dependent job. The GitHub Actions Builds guide documents the same layout, pinned to the publish action revision, and the manual GitHub App setup. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Mark a workflow run complete only after its final screenshot pass, and re-enqueue recent GitHub Builds whose dist or completed-run pass is still owed every five minutes. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Poll each connected repository's recent Replica push runs every five minutes and enqueue imports for runs whose Build is missing or can still change, so Builds import even when webhooks cannot reach the Hub. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Every minute, one worker scans the App's recent webhook deliveries from a saved checkpoint, records workflow and installation deliveries that never reached the Hub, and asks GitHub to redeliver them with bounded backoff. A lease keeps runs exclusive, and settled records age out after 30 days. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Matches the Rails repository sync interval so newly installed repositories become eligible for Build discovery sooner. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Describe the scheduled webhook redelivery, workflow run discovery, retry, and installation reconciliation jobs, their limits, and how polling keeps Builds importing when GitHub cannot reach Hub. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Share immutable imports with artifact pull recovery, verify GitHub Actions identity, and reject artifacts from earlier run attempts. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Publish dist before screenshots with optional OIDC-authenticated uploads and actionable failures while retaining artifact-only compatibility. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Restore matching immutable Builds when a branch returns to an earlier commit without overriding newer head observations. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Pin the two-job workflow to the completed actions and describe retries, outage recovery, and publishing identity boundaries. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Remove superseded upload routes, GitHub Actions OIDC publishing and action push inputs while retaining artifact recovery, branch polling and run-attempt safety. Preserve history and existing Build data. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Keep completion retryable through registration and screenshot imports, record branch deletion tombstones, recover prior-attempt artifacts, and preserve workflow ordering during polling. Page discovery, settle reused runs, and support build-only action composition. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
A full rerun now waits for its own dist. An earlier attempt's dist is used only when the Build or the current attempt's screenshots name its digest. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
A branch listing that began after a recorded deletion restores the branch, keeping its metadata and Builds. Repeated deletes refresh the tombstone. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Resume retired branch identities only with verified head continuity. Keep unrelated histories separate and guard branch observations and delayed workflow imports with owner revisions and retirement boundaries. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Anchor a retired branch only on the deleted head GitHub reports in a branch-deleting push, and only when that identity had accepted the head. SHA-less delete events and pre-migration retirements yield a separate identity instead of resuming from Hub's last observation, so a delayed delete cannot attach a replacement history to retained metadata, reviews, share links, or Builds. The migration no longer backfills. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved critical issues can select the wrong current Build, leave cached repository access usable after removal, and stall the shared import worker on crafted artifacts.
14 open issues
Restrict the workflow example to branch pushes · New Retry access-removal webhooks after authentication and routing failures · New Preserve run ordering when selecting the current Build · New Reject overlapping ZIP data ranges before decompression · New Reserve manifest bytes in the screenshot package size limit · New Limit Git metadata checks to actual metadata roots · New Keep queued workflow runs queued · New Resolve commit author from the head commit, not the run actor · New Continue branch refresh after individual head failures · New Prevent stale requests from exceeding the delivery attempt limit · New Fail on incomplete or invalid installation settings · New Reuse one GitHub client per repository discovery pass · New Test migrations against preexisting schema and history · New Use a UUID primary key for the App table · New
What changed in this PR
Adds pull-based GitHub Actions Build imports to Hub’s existing Build and artifact-storage model, with recovery for missed events and preservation of branch history.
Changes:
- Import dist packages and attach screenshots only when their digests match.
- Add webhook recovery, workflow discovery, import retries, and branch identity handling.
- Separate publishing and screenshot jobs, with supporting migrations, tests, documentation, and CI checks.
| File | Description |
|---|---|
scripts/check-ci-workflows/index.ts |
Check separate publish and screenshot jobs. |
scripts/check-ci-workflows/index.test.ts |
Cover workflow layout and documentation contracts. |
hub/test/database/github-branch-identity-migration/index.db.test.ts |
Check migration preserves retained history. |
hub/server/workers/retry-github-builds-awaiting-import/index.ts |
Retry unfinished GitHub imports. |
hub/server/workers/recover-github-webhook-deliveries/index.ts |
Compose webhook recovery dependencies. |
hub/server/workers/import-github-workflow-run/index.ts |
Compose workflow import dependencies. |
hub/server/workers/discover-github-workflow-runs/index.ts |
Compose workflow and branch discovery. |
hub/server/workers/configuration.ts |
Register import processors and recovery schedules. |
hub/server/workers/configuration.test.ts |
Cover processor registration and schedules. |
hub/server/utils/read-zip-archive/types.ts |
Define archive entries and extraction limits. |
hub/server/utils/read-zip-archive/index.ts |
Read bounded ZIP archives. |
hub/server/utils/read-zip-archive/index.test.ts |
Cover archive validation and limits. |
hub/server/utils/read-zip-archive/errors.ts |
Define archive validation errors. |
hub/server/test/create-zip-archive/index.ts |
Generate controlled ZIP test fixtures. |
hub/server/routes/api/github/webhooks/create-github-webhook-route-dependencies/index.ts |
Handle workflow events and branch deletion. |
hub/server/routes/api/github/webhooks/create-github-webhook-route-dependencies/index.db.test.ts |
Cover event queueing and retained history. |
hub/server/repositories/prototypes/retire-github-branch/index.ts |
Retire branches without deleting history. |
hub/server/repositories/prototypes/lock-imported-prototype/index.ts |
Lock eligible prototypes during registration. |
hub/server/repositories/prototypes/list-github-branch-identities/index.ts |
Read current branch identity evidence. |
hub/server/repositories/github-webhook-redeliveries/types.ts |
Define redelivery records and claims. |
hub/server/repositories/github-webhook-redeliveries/settle-github-webhook-redeliveries/index.ts |
Settle completed or exhausted redeliveries. |
hub/server/repositories/github-webhook-redeliveries/record-github-webhook-redelivery-attempt/index.ts |
Record claimed redelivery outcomes. |
hub/server/repositories/github-webhook-redeliveries/delete-settled-github-webhook-redeliveries/index.ts |
Remove expired settled recovery records. |
hub/server/repositories/github-webhook-redeliveries/create-github-webhook-redeliveries/index.ts |
Track missed deliveries idempotently. |
hub/server/repositories/github-webhook-redeliveries/claim-due-github-webhook-redeliveries/index.ts |
Claim due or abandoned redeliveries. |
hub/server/repositories/github-webhook-recovery-checkpoints/update-github-webhook-recovery-checkpoint/index.ts |
Update checkpoints under a lease. |
hub/server/repositories/github-webhook-recovery-checkpoints/claim-github-webhook-recovery-checkpoint/index.ts |
Lease webhook recovery checkpoints. |
hub/server/repositories/github-webhook-deliveries/list-claimed-github-webhook-deliveries/index.ts |
Find already-processed delivery IDs. |
hub/server/repositories/github-builds/types.ts |
Define stored run and artifact metadata. |
hub/server/repositories/github-builds/record-github-build-run-completion/index.ts |
Record completed artifact import passes. |
hub/server/repositories/github-builds/record-github-branch-heads/index.ts |
Apply branch observations and continuity decisions. |
hub/server/repositories/github-builds/read-github-build-package-state/index.ts |
Read immutable Build package identity. |
hub/server/repositories/github-builds/prepare-github-build/types.ts |
Define Build preparation inputs and outcomes. |
hub/server/repositories/github-builds/prepare-github-build/index.ts |
Prepare commit Builds and run ownership. |
hub/server/repositories/github-builds/mark-github-build-running/index.ts |
Transition owned Builds to running. |
hub/server/repositories/github-builds/list-github-builds-awaiting-import/index.ts |
Find Builds needing another import pass. |
hub/server/repositories/github-builds/list-github-builds-awaiting-import/index.db.test.ts |
Cover import retry eligibility. |
hub/server/repositories/github-builds/list-github-build-runs/index.ts |
Read saved import state for discovery. |
hub/server/repositories/github-builds/complete-github-build-success/index.ts |
Commit successful dist imports atomically. |
hub/server/repositories/github-builds/complete-github-build-failure/index.ts |
Record failures for owned unfinished Builds. |
hub/server/repositories/github-builds/attach-github-build-screenshots/index.ts |
Attach matching screenshots without replacement. |
hub/server/integrations/github/create-github-webhook-deliveries-client/types.ts |
Define webhook delivery client contracts. |
hub/server/integrations/github/create-github-webhook-deliveries-client/index.ts |
List deliveries and request redelivery. |
hub/server/integrations/github/create-github-webhook-deliveries-client/index.test.ts |
Cover pagination and redelivery responses. |
hub/server/integrations/github/create-github-actions-client/types.ts |
Define workflow run and artifact contracts. |
hub/server/index.ts |
Wire webhook-triggered import queueing. |
hub/server/domains/prototypes/register-imported-prototype/index.ts |
Register eligible successful prototypes automatically. |
hub/server/domains/prototypes/register-imported-prototype/index.db.test.ts |
Cover registration eligibility and concurrent edits. |
hub/server/domains/prototypes/record-github-branch-deletion/index.ts |
Commit deletion receipts and retirement together. |
hub/server/domains/prototypes/constants.ts |
Define the automatic-registration branch prefix. |
hub/server/domains/github-webhooks/types.ts |
Define recovery dependencies and lease contracts. |
hub/server/domains/github-webhooks/scan-github-webhook-deliveries/index.ts |
Discover missed deliveries using checkpoints. |
hub/server/domains/github-webhooks/redeliver-github-webhook-deliveries/index.ts |
Request redelivery with bounded backoff. |
hub/server/domains/github-webhooks/recover-github-webhook-deliveries/index.ts |
Coordinate leased scanning and redelivery. |
hub/server/domains/github-webhooks/constants.ts |
Define recovery windows and supported events. |
hub/server/domains/github-builds/types.ts |
Define shared import dependencies. |
hub/server/domains/github-builds/store-github-build-files/index.ts |
Store files under content-derived keys. |
hub/server/domains/github-builds/refresh-github-branch-heads/index.ts |
Check returning branch continuity. |
hub/server/domains/github-builds/prepare-github-workflow-run-build/index.ts |
Validate runs before preparing Builds. |
hub/server/domains/github-builds/import-github-workflow-run/types.ts |
Define workflow import dependencies and results. |
hub/server/domains/github-builds/import-github-workflow-run/index.ts |
Coordinate dist and screenshot import passes. |
hub/server/domains/github-builds/import-github-screenshot-package/index.ts |
Validate and store matching screenshots. |
hub/server/domains/github-builds/import-github-dist-package/index.ts |
Validate and commit dist packages. |
hub/server/domains/github-builds/get-github-workflow-run-job-definition/index.ts |
Define import payload validation and retries. |
hub/server/domains/github-builds/enqueue-github-workflow-run-retries/index.ts |
Deduplicate recovery jobs per run. |
hub/server/domains/github-builds/enqueue-github-workflow-run-import/index.ts |
Queue import passes per webhook delivery. |
hub/server/domains/github-builds/discover-github-workflow-runs/index.ts |
Discover recent unsettled workflow runs. |
hub/server/domains/github-builds/constants.ts |
Define artifact names and recovery limits. |
hub/server/domains/build-artifacts/validate-build-templates/index.ts |
Validate imported template manifests. |
hub/server/domains/build-artifacts/validate-build-templates/index.test.ts |
Cover template schema and route validation. |
hub/server/domains/build-artifacts/types.ts |
Define extracted package file kinds. |
hub/server/domains/build-artifacts/read-zip-package/index.ts |
Normalize bounded package entries. |
hub/server/domains/build-artifacts/extract-screenshot-package/index.ts |
Extract screenshots and their dist digest. |
hub/server/domains/build-artifacts/extract-screenshot-package/index.test.ts |
Cover screenshot package acceptance and rejection. |
hub/server/domains/build-artifacts/extract-dist-package/index.ts |
Extract dist and legacy combined packages. |
hub/server/domains/build-artifacts/extract-dist-package/index.test.ts |
Cover package limits and digest compatibility. |
hub/server/domains/build-artifacts/errors.ts |
Define permanent package validation errors. |
hub/server/domains/build-artifacts/digest-dist-files/index.ts |
Compute shared dist package digests. |
hub/server/domains/build-artifacts/constants.ts |
Define package limits and file patterns. |
hub/schema/prototype.prisma |
Add branch identity and selection metadata. |
hub/schema/migrations/20261216120000_github_branch_identity/migration.sql |
Add branch identity columns and index. |
hub/schema/migrations/20261215120000_github_webhook_recovery/migration.sql |
Add durable webhook recovery tables. |
hub/schema/migrations/20261210120000_github_workflow_builds/migration.sql |
Add workflow ownership and digest fields. |
hub/schema/github-webhook-redelivery.prisma |
Model durable redelivery state. |
hub/schema/github-webhook-redelivery-state.enum.prisma |
Define redelivery lifecycle states. |
hub/schema/github-webhook-recovery-checkpoint.prisma |
Model scan checkpoints and leases. |
hub/schema/build.prisma |
Store workflow run and package metadata. |
hub/docs/README.md |
Link the GitHub Actions Builds guide. |
hub/docs/development.md |
Update worker recovery guidance. |
hub/docs/database.md |
Document retained branch identity rules. |
hub/docs/build-previews.md |
Link the separate artifact import boundary. |
hub/docs/background-jobs.md |
Document import processors and recovery schedules. |
hub/docs/authentication.md |
Describe reconciliation and webhook recovery. |
hub/docs/artifact-storage.md |
Include GitHub imports as storage consumers. |
hub/docs/architecture.md |
Describe hosted imports and worker responsibilities. |
hub/client/utils/github-app-requirements/index.ts |
Require deletion and workflow-job subscriptions. |
hub/client/application/hub/github-app-creation-url/index.test.ts |
Check required App event subscriptions. |
docs/testing-and-review.md |
Explain the dependent artifact smoke jobs. |
actions/build/scripts/validate-checkout/index.test.mjs |
Cover checkout credential guard behavior. |
actions/build/scripts/validate-checkout/index.mjs |
Reject persisted checkout authentication settings. |
actions/build/scripts/validate-build-output/index.mjs |
Support configurable static output directories. |
actions/build/scripts/required-path-argument/index.mjs |
Allow callers to retain relative paths. |
actions/build/scripts/require-index-file/index.mjs |
Report configured output paths in errors. |
actions/build/scripts/prepare-build-output/index.test.mjs |
Cover safe output normalization. |
actions/build/scripts/prepare-build-output/index.mjs |
Copy validated output into fixed dist layout. |
actions/build/scripts/digest-dist-package/index.mjs |
Compute action-side package digests. |
actions/build/scripts/create-screenshot-package/index.test.mjs |
Cover digest binding and template screenshots. |
actions/build/scripts/create-screenshot-package/index.mjs |
Package screenshots with a dist digest. |
actions/build/scripts/create-package/index.mjs |
Reuse screenshot copying for combined packages. |
actions/build/scripts/create-dist-package/index.test.mjs |
Cover dist-only package creation. |
actions/build/scripts/create-dist-package/index.mjs |
Package static output without screenshots. |
actions/build/scripts/copy-screenshots/index.mjs |
Share screenshot validation and copying. |
actions/build/scripts/constants.mjs |
Name the separate screenshot artifact. |
actions/build/scripts/capture-screenshots/index.mjs |
Read templates from downloaded packages. |
actions/build/screenshots/action.yml |
Capture screenshots in a dependent job. |
actions/build/publish/action.yml |
Publish validated static output independently. |
actions/build/action.yml |
Add build-only and separate-screenshot modes. |
.github/workflows/actions-ci.yml |
Exercise publishing and screenshots across jobs. |
Review effort: Max (adaptive)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
arniebradfo
approved these changes
Nov 19, 2026
arniebradfo
left a comment
Collaborator
There was a problem hiding this comment.
The concept sounds reasonable. I have yet to test (and of course there's too much code to check as a human). But I did read the description and appreciate the mermaid chart.
Merge build/hub/new while retaining team-permission invalidation and workflow-run/job import handling. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The stale-update test hard-coded a shortened expiration that is now before the link's created_at, so the expires_at > created_at check constraint rejected it. Derive the dates from the link's createdAt. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
arniebradfo
added a commit
that referenced
this pull request
Nov 19, 2026
<!-- Use a conventional commit-style title, such as "fix(hub): retain prototype history". --> ## Why <!-- Explain the problem and why this change matters in a short, plain-English paragraph. Link the issue when applicable. --> Designers should be able to start from a template, open a real Build, review it with teammates, and share it without relying on browser mock data. This PR connects those Hub workflows to Express and PostgreSQL. The goal is to make the workflow usable in local mode first, then prove it against a real GitHub repository before Azure staging. ## What changes <!-- Describe what becomes different for a first-time reader. Explain necessary terms. Include accurate Mermaid diagrams when they clarify the proposal, using before/after diagrams when helpful. Add screenshots for meaningful UI changes. --> <!-- Omit validation sections, checklists, and routine test/CI summaries such as "CI is green" or "tests passed". Mention only known verification gaps that affect the change, not disclaimers about drafting this description. --> <!-- For UI changes, prune obsolete and duplicate stories in the affected catalogues as part of the change. Explain removed UI or consolidated coverage where needed; see hub/docs/storybook.md#ui-changes-and-pull-request-evidence. --> **On this branch:** Create uses saved templates from the latest successful default-branch Build. Users can copy the kickoff prompt or, with current GitHub write access, hand it off to Copilot. The same Build-preview system that landed in #276 serves the template previews and Build-pinned share links. Hub now saves review reactions, mentions, thread read state, and Inbox activity, and refreshes open reviews when conversations change. Repository users can edit listings and register eligible drafts. Repository administrators can view a scoped security audit and configure analytics destinations. Hosted sharing and outbound analytics are off by default. Welcome can be hidden per user, and the Replica Canvas can pair with Hub, read repository and Build status, renew its connection, and be revoked. This branch uses #300's Build importer, with webhooks and recovery polling, rather than a second importer or migration. Successful imports and automatic registration record their corresponding analytics events. #295's stored grants remain in place for Learnings; this PR still checks fresh GitHub permissions for sensitive listing, audit, sharing, and analytics actions. **Still needed before review:** Use an approved scratch GitHub repository and two accounts to verify that an Actions Build opens in the existing preview, supplies templates, and supports the Copilot handoff, listing permissions, review and Inbox delivery, and share revocation. Imported start-page and commit-author metadata are not end-to-end complete; commit-author metadata is needed for non-admin creators to manage their own hosted share links. Verify outbound analytics only against an approved receiver. Azure identity, storage, ingress, and preview DNS/TLS require a staging deployment. **Out of scope:** Redesigning the repository gallery, prototype shell, or user filters; standalone Rails Build-detail pages; one-click workflow installation; migrating Rails records; and legacy GitHub App registration and credential screens. Create does not write Git branches or run Builds. This PR does not add a template editor, an analytics dashboard, external notifications, Canvas publishing or review/share writes, Pick & polish sync, Learnings changes, or decision-model UI. ## Storybook screenshots <!-- For Hub or canvas UI changes, follow hub/docs/storybook.md#ui-changes-and-pull-request-evidence. Embed uploaded screenshots of EVERY added or changed story, including stories affected indirectly by shared code, styles, copy, or fixtures. Label each with its full story title/name, theme, and viewport. Keep this section last and refresh images after UI revisions. Name any missing story and its rendering/upload blocker; incomplete evidence is not completion. Remove this section only when no story presentation changes. --> <details> <summary>Components/Mention input — light, 1440 × 1000 viewport</summary>   </details> <details> <summary>Hub/Features/Review/Thread Conversation — light, 1440 × 1000 viewport</summary>         </details> <details> <summary>Hub/Features/Review/Thread Message — light, 1440 × 1000 viewport</summary>        </details> <details> <summary>Hub/Features/Workspace Sidebar — light, 1440 × 1000 viewport</summary>    </details> <details> <summary>Hub/Pages/Canvas/Connection — light, 1440 × 1000 viewport</summary>        </details> <details> <summary>Hub/Pages/Home — light, 1440 × 1000 viewport</summary>        </details> <details> <summary>Hub/Pages/Inbox prototype — light, 1440 × 1000 viewport</summary>      </details> <details> <summary>Hub/Pages/Prototype Review — light, 1440 × 1000 viewport</summary>                           </details> <details> <summary>Hub/Pages/Replica Browse — light, 1440 × 1000 viewport</summary>              </details> <details> <summary>Hub/Pages/Repositories/Analytics — light, 1440 × 1000 viewport</summary>              </details> <details> <summary>Hub/Pages/Repositories/Create — light, 1440 × 1000 viewport</summary>               </details> <details> <summary>Hub/Pages/Welcome — light, 1440 × 1000 viewport</summary>      </details> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.



Why
The new Hub could only show local or seeded Builds. Prototype repositories build in GitHub Actions, so Hub needs to import those Builds itself, as the Rails Hub on
maindoes. Imports must never lose data: they have to be safe to repeat, recover from missed events, and never replace or delete an existing Build or artifact.What changes
Hub now imports Builds from a prototype repository's
replica.ymlworkflow. The design is pull-only. GitHub tells Hub that a run changed, and Hub downloads the run's artifacts through the GitHub API. The workflow never uploads to Hub directly.The build action can now run as two jobs. A publish job uploads the
replica-build-v1dist package, and a dependent job captures screenshots asreplica-screenshots-v1. Hub starts importing the dist when the publish job finishes, so the preview can become available before screenshots end. That timing is not guaranteed; it depends on webhook delivery and the import queue. Screenshots attach later, and only when their dist digest matches the Build. The existing single-step action still produces its previous combined package, and a build-only mode avoids a duplicate upload.hub/docs/github-actions-builds.mdhas a ready-to-copy two-job workflow. CI is configured to exercise that layout.There is one Build per prototype identity and commit. A branch usually has one identity, but a deleted and recreated branch can have a separate one. The first successful dist import fixes its digest, and later attempts never replace it. Storage keys are content-addressed and are never deleted. Re-running only the failed screenshot job reuses the earlier attempt's dist when its digest matches the Build.
Because GitHub does not retry failed webhooks, recovery jobs from Rails are ported onto BullMQ:
Whichever path commits a valid dist first wins.
A successful Build on a
proto/branch now registers its Prototype automatically by settingregisteredAt. Registration never overwrites a saved name or description. The default branch,replica/install-workflow, and deleted branches never register. Gallery and list queries are unchanged;registeredAt !== nullremains the contract for the teammate who owns that display.Branch
deleteevents and branch-deleting pushes retire a Prototype without removing any of its data. A returning branch resumes that identity only when GitHub proves continuity: the deleted head, taken from the push'sbeforeSHA and accepted by that identity, equals or is an ancestor of the returning head. Otherwise the branch gets a separate, unregistered Prototype, and the retired one keeps its name, reviews, share links, and Builds. This follows the Railsbranch_presenceprecedent.The migrations preserve existing data. The identity migration intentionally does not backfill a retired head, unlike Rails. Branches retired before it get a separate identity when they return.
The Hub's GitHub App now needs Actions: read and Contents: read permissions. It must also subscribe to the Workflow runs, Workflow jobs, Push, and Branch or tag deletion events. Existing Apps must be updated by hand, and each installation must accept any newly added permission. The existing setup stories retain their distinct missing-settings, configured, and connection-result states; their shared checklist now includes the required events.
Known gaps and limitations:
branches: ['proto/**']covers nested prototype branches. The tag-ambiguity review thread remains open for this accepted limitation.deleteevent carries no SHA. If only that event arrives, or the branch was retired before the migration, a returning branch gets a separate identity: no data is lost, but continuity is.Storybook screenshots
Captured from
ccc86bdcusing isolated Microsoft Edge. Each image is a full-page capture with a 1440 x 1000 viewport and the light theme.Hub/Pages/GitHub Setup/Setup / Not Configured - Create manually - light - 1440 x 1000
Hub/Pages/GitHub Setup/Setup / Not Configured - Reuse an existing App - light - 1440 x 1000
Hub/Pages/GitHub Setup/Setup / Incomplete - light - 1440 x 1000
Hub/Pages/GitHub Setup/Setup / Configured - light - 1440 x 1000
Hub/Pages/GitHub Setup/Setup / Connection Verified - light - 1440 x 1000
Hub/Pages/GitHub Setup/Setup / Connection Failed - light - 1440 x 1000