Four-Repository Passport Deployment

This runbook is for the IDEAL Lab IT administrator. The active 2026 service uses IDEALLab/onboarding-IT as source and soheylm-passport-sandbox for the three runtime repositories. Do not merge the overhaul or invite learners until every required production gate below is green.

1. Build From One Reviewed Revision#

From a clean reviewed onboarding-IT commit:

python3 scripts/export_exercises_repo.py /tmp/passport-exercises
python3 scripts/export_gh_passport.py /tmp/gh-passport
git clone git@github.com:soheylm-passport-sandbox/onboarding-control.git /tmp/onboarding-control
python3 scripts/export_onboarding_control.py --update-existing /tmp/onboarding-control
python3 scripts/render_deployment_assets.py --check

Diff each export before pushing. Exercises and launcher are public; onboarding-control is private. While the overhaul PR remains unmerged, handbook_ref must name this reviewed branch. Change it to main only in the reviewed cutover commit.

Never replace the control repository with a fresh directory or use an unqualified rsync --delete: assignments, enrollments, registry events, and completion records are append-only operational state. --update-existing refuses a dirty clone, a branch other than main, or an origin other than the configured control repository. It preserves trusted state while replacing generated code and rebuilding the operational views.

2. Publish The Static First Contact#

Build the stateless browser product locally from the reviewed revision:

PNPM=pnpm python3 scripts/build_web.py \
  --source-ref "$(git rev-parse HEAD)" \
  --site-url https://ideal-passport.pages.dev
cd platform/cloudflare-worker
pnpm install --frozen-lockfile
pnpm exec wrangler pages deploy ../../web/dist --project-name ideal-passport

Expected: Cloudflare prints the deployed HTTPS URL. Open /getting-started/ without GitHub login and verify all internal links. This Pages project stores no learner identity or progress and needs no GitHub repository access or secret.

3. Protect Public Exercises#

Protect passport-exercises:main: require PRs and conversation resolution, disable force pushes and deletion, and require the trusted controller Check Run once live. Keep the repository free of privileged workflows and secrets.

4. Configure Two GitHub Apps#

Controller App#

Install only on passport-exercises:

Subscribe only to Pull request. Configure the deployed Cloudflare Worker as Webhook URL and a new random webhook secret. Store this App's client ID and private key only in private onboarding-control as CONTROLLER_APP_CLIENT_ID and CONTROLLER_APP_PRIVATE_KEY. The immutable App ID must match platform/deployment.json and the launcher release.

Dispatch App#

Install only on private onboarding-control:

Do not subscribe it to public events. Put its App ID, installation ID, and PKCS#8 private key only in Cloudflare Worker secrets.

5. Deploy The Signed Worker#

Follow platform/cloudflare-worker/README.md. Review wrangler.toml, run the local Worker tests, enter five secrets through hidden Wrangler prompts, deploy, and update the Controller App webhook URL. Never broaden either App installation as a debugging shortcut.

A successful webhook forwards only delivery ID, exercise repository, PR number, and head SHA. GitHub's delivery log must show 202 controller_dispatched.

6. Lock Cost#

The private workflow has one serial assessment per changed learner SHA, bounded job timeouts, and workflow concurrency. A recovery cron runs only four times per day. No large runner is allowed.

Before enabling a cohort:

1. confirm the sandbox organization has no payment method, so usage stops at included quota; or
2. if a payment method exists, set a GitHub Actions product budget with Stop usage when budget limit is reached.

Keep usage alerts enabled. Measure minutes after five synthetic learners and project the full cohort. A notification is not a spending lock.

7. Publish The Launcher#

The release workflow tests and emits Windows x64, macOS x64/arm64, and Linux x64/arm64 binaries. Tag the reviewed matching release, then test:

gh extension install soheylm-passport-sandbox/gh-passport --force --pin v0.3.0
gh passport version

Do not ask learners to bypass Gatekeeper, SmartScreen, antivirus, or execution policy.

8. Enroll Learners#

Enroll GitHub usernames and one operational reviewer asynchronously in private onboarding-control. Do not store operating system, answers, credentials, or research context in enrollment. The learner starts from the public first-contact page and does not join the sandbox organization.

9. Production Transaction#

Before invitation, use a non-admin synthetic learner to prove:

1. no public artifact exists before browser consent;
2. start creates exactly one personal fork and central draft transport PR;
3. a mission submission causes one signed Worker dispatch;
4. the controller assesses the exact SHA without credentials or network;
5. the expected trusted App publishes one Check Run and sanitized feedback;
6. wrong signature/repository/App/branch/SHA inputs cause no assessment;
7. an unchanged redelivery does not increase attempts or duplicate records;
8. completion writes one private record, closes without merging, and resumes;
9. public help works asynchronously without a secret or private log.

10. Cutover And Rollback#

After qualification, merge the reviewed onboarding branch, change handbook_ref to main, rebuild all four products from the same commit, and publish the first-contact URL. Rollback pins a previously reviewed matching curriculum, launcher, exercises, controller, Worker, and static build. Never delete public records or private completion history.

Production Gates#

• Static first contact is public and tested without authentication.
• passport-exercises is public and protected.
• gh-passport is tagged and installable on clean Windows, macOS, and Linux.
• onboarding-control is private with controller credentials configured.
• Controller App is limited to passport-exercises.
• Dispatch App is limited to onboarding-control.
• Cloudflare Worker signature and real webhook transaction pass.
• Paid Actions overage is impossible and alerts are enabled.
• Scheduled recovery and exact-SHA assessment succeeded in the sandbox on 2026-09-02.
• One synthetic non-admin learner completes the full public-record loop.
• Real Euler CPU, NAS, Blade, and Windows SSH pilots pass where claimed.
• No privileged key appears in public code, workflow, artifact, or log.
• The overhaul PR is reviewed and remains unmerged until cutover approval.