Setup: Onboarding a New App

The step-by-step story is on the Tutorial page. This page is about actually doing it: which tool to use, which repos to have open, and how to run the guided skills that encode everything the tutorial describes.

1. Open a multi-repo workspace

Use VS Code, Cursor, or the Claude Code CLI/extension — anything that can run Claude Code with more than one folder open at once. Skills are discovered from a .claude/skills/ folder in whichever repos are part of your current workspace, so you need the relevant repos checked out and open together, not one at a time.

Clone (or open) these three

u2i/{your-new-app}Dockerfile, Helm chart, deploy/ pipeline files. Later, the first real deploy and verification.
u2i/u2i-gcp-infrastructureRegisters the app in foundation (CI/deploy service accounts, Cloud Build triggers, Artifact Registry). Visited twice — once to register, once later to delegate DNS.
u2i/u2i-infraNamespaces, Workload Identity, DNS subzone, RBAC — reconciled onto the cluster by Config Sync.

2. Run the skills, in order

Each skill lives inside the repo it edits, not here — this keeps it next to the code it describes, so a PR that changes that code has a natural reason to update the skill in the same commit, instead of a separate docs page quietly drifting out of date. With the workspace open, type the skill name (e.g. /register-app) and follow along — each one stops and asks before pushing, merging, or applying anything.

  1. 1

    /scaffold-and-deploy-app in the new app's own repo

    Scaffold the Dockerfile, Helm chart, and deploy/ files.

  2. 2

    /register-app in u2i-gcp-infrastructure

    Part 1 — register the app in foundation.

  3. 3

    /onboard-app in u2i-infra

    Namespaces, Workload Identity, DNS subzone, RBAC.

  4. 4

    /register-app in u2i-gcp-infrastructure

    Part 2 — delegate the DNS subzone, now that step 3 created it.

  5. 5

    /scaffold-and-deploy-app in the new app's own repo

    First real deploy and end-to-end verification.

Skip steps 4 and the DNS parts of step 3 if the app has no public hostname.

What the skills will never do on their own

Every skill in this flow prepares local commits and stops for you at every repo/state boundary. None of them run git push, git merge, terraform apply, kubectl apply, or approve a Cloud Deploy rollout by themselves — even though some of those are pre-approved by this platform's general tooling conventions elsewhere. Onboarding a new app touches shared, live infrastructure across three repos, so every push, merge, and approval is a deliberate, human decision, every time.

One repo has a sharper edge than the others

In u2i-infra, opening a PR can already deploy the change to the live nonprod cluster, before anyone reviews or merges it — its PR-validation trigger and its merge trigger currently share the same pipeline. That's a known platform issue, not something the skill can route around. The onboard-app skill there will call this out explicitly before you push, but it's worth knowing going in.