Repository navigation
feat(hub): support manual App connections and VM operations - #146
Merged
Merged
Conversation
Add bootstrap-protected manual setup for one verified installation, independent of App registration ownership. Preserve manifest connections and scope polling, webhooks, diagnostics, and recovery to the approved installation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Accept underscore-containing managed-user logins in authenticated App ownership metadata while retaining the existing App ID, owner type, organization-login, and App-slug checks. Cover cross-account import and subsequent polling, plus invalid identity boundaries. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4e113915-1ab2-4d2e-ac75-4f9b1c974604
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4e113915-1ab2-4d2e-ac75-4f9b1c974604
Generalize VM installation, Azure DNS and identity setup, image updates, source builds, patches, backups, and GitHub App connection instructions. Link the operator walkthroughs from the shared and Hub documentation indexes. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4e113915-1ab2-4d2e-ac75-4f9b1c974604
Explain both Credentials and General layouts for client secrets and private keys, keep the setup stories aligned, and cover an active pinned installation alongside its removed state. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4e113915-1ab2-4d2e-ac75-4f9b1c974604
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Manual setup can invalidate an open registration and leave App credentials unsaved, while credential autofill can persist a bootstrap secret and send it to GitHub.
5 open issues
What changed in this PR
This PR lets a self-hosted Hub connect an independently registered GitHub App to one explicitly approved installation, while preserving the existing manifest setup flow. It also adds operator guidance for installing and maintaining Hub on a VM.
Changes:
- Adds bootstrap-protected manual connection, credential verification, and setup UI.
- Keeps polling, webhooks, and delivery recovery bound to the approved installation without deleting retained review data.
- Adds regression coverage and walkthroughs for deployment, updates, source builds, backups, and recovery.
| File | Description |
|---|---|
hub/test/models/github_app_pinned_installation_test.rb |
Covers pinned installation boundaries and lifecycle behavior. |
hub/test/models/github_app_manual_import_test.rb |
Covers import verification, authorization, and atomic persistence. |
hub/test/integration/github_app_manual_setup_test.rb |
Covers protected forms and multipart connection requests. |
hub/README.md |
Links operator walkthroughs and explicit release selection. |
hub/docs/source-image-builds.md |
Documents reviewed source builds, patches, and smoke checks. |
hub/docs/security-rate-limits.md |
Documents pinned webhook recovery boundaries. |
hub/docs/security-audit.md |
Documents manual connection audit records. |
hub/docs/README.md |
Indexes installation and maintenance walkthroughs. |
hub/docs/manual-vm-installation.md |
Adds an ordered Linux VM installation guide. |
hub/docs/manual-updates.md |
Documents image replacement while retaining data and secrets. |
hub/docs/github-app-setup.md |
Explains manual connection, verification, and installation lifecycle. |
hub/docs/deployment.md |
Links walkthroughs and clarifies image update behavior. |
hub/docs/backups-and-restore.md |
Adds consistent backup and clean-target recovery procedures. |
hub/docs/azure-vm-deployment.md |
Documents Azure networking, DNS, identity, and HTTPS. |
hub/docs/authentication-and-repository-authorization.md |
Clarifies visibility and access for cross-account Apps. |
hub/docs/architecture.md |
Describes the App and installation account boundary. |
hub/db/schema.rb |
Records pinned installation fields and constraints. |
hub/db/migrate/20261026200000_add_pinned_github_app_installations.rb |
Adds installation policy and account metadata. |
hub/config/routes.rb |
Exposes manual setup display and submission routes. |
hub/config/locales/github_app.en.yml |
Adds pinned connection status and recovery guidance. |
hub/config/locales/github_app_setup.en.yml |
Adds manual setup instructions, fields, and messages. |
hub/app/views/github_apps/show.json.props |
Supplies pinned connection guidance to administration pages. |
hub/app/views/github_apps/_configuration.json.props |
Displays the approved installation account and state. |
hub/app/views/github_app_setup/register.json.props |
Supplies the manual connection link. |
hub/app/views/github_app_setup/manual.tsx |
Connects Rails page data to the manual setup page. |
hub/app/views/github_app_setup/manual.json.props |
Supplies manual form data and GitHub settings. |
hub/app/views/github_app_setup/install.json.props |
Selects manual connection completion guidance. |
hub/app/models/webhook_redelivery.rb |
Filters recovery work by the approved installation. |
hub/app/models/webhook_recovery_checkpoint/scan.rb |
Filters scanned delivery metadata by installation. |
hub/app/models/security_audit_event.rb |
Allows bootstrap-sourced audit events. |
hub/app/models/github_webhook.rb |
Checks pinned installation and account identity before admission. |
hub/app/models/github_app_setup.rb |
Verifies and atomically imports manual App connections. |
hub/app/models/github_app_configuration/ownership.rb |
Preserves pinned connections across App ownership changes. |
hub/app/models/github_app_configuration/installation.rb |
Verifies and synchronizes the selected installation. |
hub/app/models/github_app_configuration/diagnostics.rb |
Checks pinned installation and account reachability. |
hub/app/models/github_app_configuration.rb |
Defines installation policy, identity guards, and import auditing. |
hub/app/javascript/pages/github-app-setup-show-page/stories.tsx |
Updates bootstrap setup copy. |
hub/app/javascript/pages/github-app-setup-register-page/types.ts |
Adds manual link properties. |
hub/app/javascript/pages/github-app-setup-register-page/stories.tsx |
Shows the manual connection entry point. |
hub/app/javascript/pages/github-app-setup-register-page/index.tsx |
Renders the manual connection link. |
hub/app/javascript/pages/github-app-setup-register-page/index.test.tsx |
Updates registration page test data. |
hub/app/javascript/pages/github-app-setup-manual-page/types.ts |
Defines manual setup presentation data. |
hub/app/javascript/pages/github-app-setup-manual-page/styles.css |
Styles instructions, settings, and confirmation controls. |
hub/app/javascript/pages/github-app-setup-manual-page/stories.tsx |
Adds default and failed connection stories. |
hub/app/javascript/pages/github-app-setup-manual-page/index.tsx |
Renders instructions and the credential upload form. |
hub/app/javascript/pages/github-app-setup-manual-page/index.test.tsx |
Covers form fields, confirmation, uploads, and errors. |
hub/app/javascript/pages/github-app-setup-install-page/stories.tsx |
Adds manual connection completion coverage. |
hub/app/javascript/pages/github-app-page/stories.tsx |
Adds active and removed pinned installation states. |
hub/app/controllers/github_app_setup_controller.rb |
Handles authorized manual setup, import, and completion. |
docs/README.md |
Links the Hub operator walkthroughs. |
docs/prototype-environment.md |
Incorporates manual App connection and VM setup options. |
Review effort: Max (auto)
nshki
approved these changes
Oct 28, 2026
Co-authored-by: Nishiki <hello@nshki.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: weastler <32074613+weastler@users.noreply.github.com>
Co-authored-by: weastler <32074613+weastler@users.noreply.github.com>
Co-authored-by: weastler <32074613+weastler@users.noreply.github.com>
Co-authored-by: weastler <32074613+weastler@users.noreply.github.com>
Preserve installation data while renaming the owner type, simplify verified-owner login validation, name the signed-bigint limit, and clarify who can read Hub review conversations. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4e113915-1ab2-4d2e-ac75-4f9b1c974604
Retain setup throttling guidance from main alongside administrator handoff instructions, preserving the manual App review fixes. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4e113915-1ab2-4d2e-ac75-4f9b1c974604
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
Some Hub installations need to register a GitHub App separately and install it in a different account. Operators also need a clear path from a new VM to a working Hub, with maintenance instructions that protect stored Builds, reviews, and encryption keys.
What changes
Adds a bootstrap-protected flow for creating an App manually or connecting an existing one. Hub verifies the App and selected installation before saving credentials, accepts managed-user registration logins, and keeps the connection bound to the approved installation rather than following the App owner to another account. Polling, webhooks, and delivery recovery respect that boundary. Suspension or removal makes repositories unavailable without deleting retained review data; the existing manifest setup flow remains supported.
Adds linked operator walkthroughs for VM installation, Azure networking and DNS, image updates, source builds, reviewed patches, backups, and clean-target recovery. Deployment-specific values use placeholders. The App guide explains credential locations, separate setup and webhook secrets, App-wide settings, and the sign-in and webhook checks that still need to happen after connection.
Updates the setup guidance for both GitHub Credentials and older General layouts. Story coverage includes manual setup, connection failure and completion, and active or removed approved installations alongside the supported manifest flow.
Local full-suite verification is not clean: the gem audit reports the existing
crass1.0.7 sanitizer advisory, dependency-age lookups cannot reach the public npm registry, and local-mode and extension Git tests encounter Docker bind-mount ownership failures. The dependency pins and affected test files are unchanged frommain. These gaps and the missing screenshot attachments below keep this PR in draft.Storybook screenshots
All seven affected stories rendered with synthetic data in the browser canvas, but their required GitHub screenshot attachments are still missing. The canvas exposes no image-file export action, and the configured isolated Playwright MCP server fails to start with
No such file or directory. Screenshot evidence remains incomplete for every story listed here.