Migrate launcher to official Builder accounts (Vercel integration, GitHub OAuth app, hosting)

[sktbrd]

Summary

The launcher currently runs entirely on personal accounts (@sktbrd): the Vercel integration, the GitHub OAuth App, the hosting Vercel project, and the template repo all live under an individual. Before this is an official Builder tool, all of it needs to move to the official Builder org/team so it survives account changes, shares access across the team, and presents as an official integration to users.

This is a coordination task — it can't be done solo because it requires owner access to the official Builder GitHub org and Vercel team. This issue tracks the migration with a step-by-step tutorial.

Fill in before starting:

• Official GitHub org: <builder-github-org> (e.g. nounsbuild)
• Official Vercel team: <builder-vercel-team>
• Production domain: <prod-domain> (e.g. deploy.nouns.build)

---

What has to move

Asset	Currently	Target
Vercel Integration (OAuth client)	personal Vercel account	official Vercel team
GitHub OAuth App	personal GitHub	official GitHub org
Hosting Vercel project (this app)	personal Vercel	official Vercel team
Template repo (TEMPLATE_REPO)	sktbrd/builder-template-app	<builder-github-org>/builder-template-app
Production env vars	personal project	official project
OAUTH_STATE_SECRET	dev value	freshly generated for prod

The env var names the app reads (see .env.example):
TEMPLATE_REPO, OAUTH_STATE_SECRET, GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GITHUB_REDIRECT_URI, VERCEL_CLIENT_ID, VERCEL_CLIENT_SECRET, VERCEL_REDIRECT_URI, VERCEL_INTEGRATION_SLUG.

---

Tutorial

0. Prerequisites

• Owner/admin on the official Builder GitHub org
• Owner/admin on the official Builder Vercel team
• Agreement on the production domain

1. Transfer the GitHub repo (optional but recommended)

If the launcher repo itself should be org-owned:

• Settings → General → Transfer ownership → transfer sktbrd/builder-deploy-direct to <builder-github-org>
• Update any local clones' remotes: git remote set-url origin git@github.com:<builder-github-org>/builder-deploy-direct.git

2. Move the template repo

• Transfer (or re-fork) sktbrd/builder-template-app into <builder-github-org>
• This becomes the new TEMPLATE_REPO=<builder-github-org>/builder-template-app

3. Recreate the GitHub OAuth App under the org

GitHub OAuth Apps cannot be transferred between owners — recreate it:

• https://github.com/organizations/<builder-github-org>/settings/applications → New OAuth App
• Homepage URL: https://<prod-domain>
• Authorization callback URL: https://<prod-domain>/api/github/callback
• Generate a client secret
• Record GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
• GITHUB_REDIRECT_URI=https://<prod-domain>/api/github/callback

Note: scope is public_repo read:user (set in code). A future improvement is migrating to a GitHub App for per-repo scoping — tracked separately, out of scope here.

4. Recreate the Vercel Integration under the team

Integrations are owned by the account/team that creates them — recreate under the team:

• https://vercel.com/dashboard/integrations/console (as the official team) → Create
• Slug: e.g. builder-deploy-direct → VERCEL_INTEGRATION_SLUG
• Redirect URL: https://<prod-domain>/api/vercel/callback
• Scopes: Projects Read/Write, Deployments Read, User Read, + Git access
• Record VERCEL_CLIENT_ID, VERCEL_CLIENT_SECRET
• VERCEL_REDIRECT_URI=https://<prod-domain>/api/vercel/callback

5. Move / recreate the hosting project on the official team

• Either Transfer the existing Vercel project to <builder-vercel-team> (Project → Settings → Advanced → Transfer), or create a new project on the team from the GitHub repo
• Connect it to the (possibly transferred) GitHub repo so pushes to main auto-deploy
• Attach the production domain <prod-domain>

6. Set production environment variables (official project)

In the official Vercel project → Settings → Environment Variables (Production scope):

TEMPLATE_REPO=<builder-github-org>/builder-template-app
OAUTH_STATE_SECRET=<openssl rand -hex 32>
GITHUB_CLIENT_ID=<from step 3>
GITHUB_CLIENT_SECRET=<from step 3>
GITHUB_REDIRECT_URI=https://<prod-domain>/api/github/callback
VERCEL_CLIENT_ID=<from step 4>
VERCEL_CLIENT_SECRET=<from step 4>
VERCEL_REDIRECT_URI=https://<prod-domain>/api/vercel/callback
VERCEL_INTEGRATION_SLUG=<from step 4>

• Generate a fresh OAUTH_STATE_SECRET (don't reuse the dev value)
• Redeploy so the new env takes effect

7. Decommission the personal setup

• Delete the personal Vercel integration
• Delete the personal GitHub OAuth App
• Remove the personal hosting project (after the official one is verified)
• Rotate/revoke any secrets that were used during dev

---

Verification checklist (post-migration)

• https://<prod-domain>/api/me returns {"vercel":{"connected":false},"github":{"connected":false}}
• https://<prod-domain>/api/debug returns 404 (prod-gated)
• Connect Vercel → redirects to the official integration, returns successfully
• Connect GitHub → OAuth consent shows the official app name
• Full flow: fork → configure → deploy → live URL appears on the "You're live" screen
• Callback URLs all resolve to <prod-domain> (no personal-account references remain)

Notes / risks

• OAuth Apps and Vercel integrations can't be transferred — they must be recreated, so client IDs/secrets change. Plan a short window where the old and new exist together, then cut over env vars and redeploy.
• Users who already authorized the personal apps will simply re-authorize the official ones; no user data is stored server-side, so there's nothing to migrate on the user side.