ADR: what blocked a first AWS deployment (August 2026)

[wooheum-xin]

Notes from standing up a fresh --target aws deployment, following the process in CONTRIBUTING.md — a .md file in adrs/, informal, describing what we hit rather than proposing an implementation.

Seven things stopped the deployment until each was worked around. Roughly by how much damage they do:

1. ADMIN_GRANTS is a first-boot seed, not a setting. Seeding an address that cannot sign in locks the deployment out of its own Admin area, and recovery needed a one-off ECS task writing to admin_grants directly because RDS is VPC-private and ECS Exec is off.
2. The gh-2.96.0-1 pin in the MicroVM agent image has rotted — the RPM repo drops old versions, so qm infra build-image fails. AWS surfaces no diagnostic at all: CREATE_FAILED with no stateReason and a log group with no stream.
3. Published images are amd64 only while the scaffold defaults architecture to arm64.
4. The npm audit gate in deploy/core/Dockerfile blocks --build-from when a production advisory has no fix available.
5. Running the CLI from a source checkout hits the registry.invalid sentinel and fails deep into the deploy, after infrastructure exists and secrets are pushed.
6. Quoted values in .env become part of the secret and travel to the provider.
7. The agent misdiagnoses missing credentials in shared scopes, pointing users at an administrator setting that does not exist instead of the keychain grant flow.

Plus smaller notes on infra delete-image, secret-only changes not restarting tasks, and the public-URL check assuming CloudFront when a proxying CDN sits in front of the ALB.

Happy to expand on any of these, and glad to test fixes against a live AWS deployment.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[wooheum-xin]

One follow-up on the gh pin, since I could check it directly.

The RPM repository at cli.github.com/packages/rpm currently carries exactly one gh version — 2.97.0-1. 2.96.0-1 is gone from the metadata entirely, so the pin in aws/microvm-agent/Dockerfile and its copy under cli/templates/ cannot resolve today.

Worth noting that cli/test/microvm-dockerfile.test.ts asserts a pin is present (/dnf install -y gh-\d+\.\d+\.\d+-\d+/), so dropping the pin is a test change too, not just a Dockerfile one. Either direction works from our side — we bumped to 2.97.0-1 locally to get building again, which is the smaller change but will rot the same way the next time the repo rolls forward.