[jayleaton]

Summary

A fresh clone of the template now reaches a live Railway project in one command, with no manual Railway or GitHub step first. Previously, the first make railway-apply dead-ended on "You don't have access to the GitHub repo" until the Railway GitHub app was installed.

railway login
make railway-doctor   # login, workspace, SSH key, GitHub access, Doppler -> prints fixes
make railway-setup    # project, envs, services, DBs, domains, secrets, first deploy, /healthz checked

make railway-setup
├─ platform.yaml: --project/--workspace/--environments/--admin/--region/--repo (or PLATFORM_*)
│    written in place, comments and layout kept; project/repo: auto = checkout's origin
├─ ensureProject (asks once; --yes for agents, else exit 3)  -> ensureEnvironments
├─ source: gitHubRepoAccessAvailable (refused for CLI tokens) / already connected?
│    no -> graph without a source (PLATFORM_SOURCE=upload)
├─ per env: IaC apply -> DB password fix -> domains -> secrets (generated + placeholders)
├─ serviceConnect(web, repo) = the real access check
│    ok   -> re-apply with the GitHub source: deploy-on-push, same services
│    fail -> railway up the services without a live deployment
│            + next step: Railway GitHub app install URL (account preselected), re-run
└─ wait for deployments, GET /healthz -> --json summary, exit 0 / 5 (unhealthy)

• Agent-friendly:
  • --yes, plus --json: one object on stdout (ok, project.{id,url}, source, each env's service url/deployment/health, nextSteps) with logs on stderr.
  • Exit codes 0 ok, 1 error, 2 plan pending, 3 needs --yes, 4 preflight failed, 5 unhealthy.
  • New AGENTS.md section "Deploy to Railway (for agents)". The README quick start is three commands.
• Production boots on day one: setup provisions a RESEND_API_KEY placeholder, and the next steps tell the user to replace it.
• New Railway findings, drafted in docs/railway-go-iac-issues.md (scratch: CI warm-run measurement (do not merge) #15–fix(auth): cheap argon2 in test binaries so -race suites stay small #17):
  • a deleted database's volume is re-attached by name to the next database;
  • GitHub queries are refused for CLI tokens;
  • project names are limited to 32 characters.

Evidence

Run in JJ's account (workspace "JJ Eaton's Projects", Pro), CLI 5.71.0, one throwaway project. The brief's name go-fast-stack-bootstrap-test-20261022 is 37 characters, and Railway rejects names over 32 (Project names must be between 1 and 32 characters.), so the project was go-fast-stack-boot-test-261022 (0490dac3-…5403). repo: jayleaton/ai-patterns-go, environments staging,production.

• Before: make railway-apply on a repo Railway can't read: You don't have access to the GitHub repo jayleaton/ai-patterns-go…, apply failed, nothing deployed (PR feat(deploy): one-config Railway setup with Go IaC (deploy/platform.yaml) #39 test).
• After:

Run	What	Result
1	from zero, --yes --json (12:14→12:32)	project + staging created. Railway could already read this repo, so serviceConnect succeeded and both envs deployed from GitHub (8b120a3). The production DB got Railway's literal secret(…) password, and setup replaced it. /healthz 200 on both. ok:true exitCode:0 source:"github"
2	re-run	no changes in both envs, no new deployments, both healthy, exit 0
3–4	fallback: services deleted, --repo jayleaton/railway-bootstrap-no-access-probe (doesn't exist, so Railway can't read it)	serviceConnect → User does not have access to the repo. Setup deployed by railway up, and both envs ended health ok, deployment SUCCESS with source:"upload". nextSteps[0]: Install Railway's GitHub app … https://github.com/apps/railway-app/installations/new/permissions?target_id=58495321 …, then re-run make railway-apply. The re-run didn't redeploy the already-live staging.
5	--repo jayleaton/ai-patterns-go again (stands in for "after installing")	GitHub: connected …; switching every service to deploy-on-push. Still exactly 2 services (postgres, web). Both envs' latest deployments come from GitHub (7fcc091), /healthz ok, exit 0. The next plan reports pendingChanges: 0.
doctor	--json	all checks ok (ssh key matched dev-box-workers-behind-api); without --yes and with no TTY, apply exits 3 before creating anything

The fallback test turned up two problems:

• A real code issue, now fixed: a failed upload used to abort the run. It now continues to the summary and exits 5.
• A Railway trap, issue draft scratch: CI warm-run measurement (do not merge) #15: after my service delete, the leftover production volume came back with the old data, so web refused to boot on old 2FA keys. I cleared the 0-user throwaway DB's authKey rows and the re-run recovered. A from-zero project can't hit this.

Cost: the test project cost $0.0045 (Railway usage). It was deleted after matching its exact name and ID; Railway scheduled the removal. Railway's 2026-10-21 incident was still open (deploy queueing for Pro): one deployment sat in DEPLOYING until the 15-minute wait ran out, while /healthz stayed ok.

Checks (pre-push, per COMMON.md): gofmt clean, go vet (module + .railway/railway.go), golangci-lint on deploy/ 0 issues, deploy/platform tests (new: Resolve, byte-preserving Edit, ForceUpload, 32-char names), actionlint. Full CI on GitHub Actions.

Not verified: a real GitHub app install. Railway could already read this repo, so the switch was shown with a nonexistent repo and then the real one. The admin path wasn't run in this test.

Merge Danger

Door: two-way. Nothing touches Railway on merge. platform.yaml now defaults project/repo to auto, so a fork whose origin is owner/name gets project name instead of the old hardcoded ai-patterns-go. Revert to restore.

Blast Radius: deployment. deploy/ (its own module), the railway Make targets (now @-silent, built into bin/railway-setup), README and AGENTS. App code is unchanged.

🤖 Generated with Claude Code