| name | onboard-app |
| description | Onboard or offboard an app to the pr-preview PR-preview platform. Use when asked to add/onboard an app or repo to PR previews, give an app a preview URL, deploy an ECR image as a preview, scaffold preview workflows for a repo, or tear down / offboard / remove an app's previews. Backed by scripts/onboard-app.sh. |
onboard-app
One-step onboarding/offboarding for the PR-preview platform. The backing script
scripts/onboard-app.sh auto-adapts to whatever the app is, so even
apps not built for this platform "just work."
The platform deploy role trusts the whole org (repo:<org>/*), so
onboarding a repo needs no CDK/platform change — just the secret + workflows.
Pick the mode
- The app/image is already in the cluster or ECR (e.g. example-app's prod
image) and you want a live preview now → image mode.
- An app repo should deploy previews automatically on every PR → repo mode
(scaffolds the caller workflows).
- Remove an app's previews → offboard mode.
image mode — deploy a preview from an image
scripts/onboard-app.sh image --image <ecr-ref:tag> --pr <n> \
[--secret <k8s-secret>] [--base-domain <d>] [--port <p>]
It probes the image and auto-detects: container port, routing mode (host
if the app serves at /, path if it bakes basePath), and whether
/api/health returns a sha (strict fresh-deploy gate) or not
(probe-only readiness). If --secret is given, its keys are copied into the
namespace and wired as env. Prints the preview URL + a kubectl port-forward
line for browser access (no DNS).
repo mode — scaffold a repo onto the platform
scripts/onboard-app.sh repo --repo <org/app> [--routing path|host]
Generates .github/workflows/preview.yml + preview-teardown.yml (ALB host and
ECR repo auto-filled), prints the exact gh secret set AWS_DEPLOY_ROLE_ARN ...
command, and prints the image contract to meet (port, /api/health sha,
basePath in path mode, non-root UID 1000, read-only rootfs). See
docs/onboarding.md.
offboard mode — remove an app's previews
scripts/onboard-app.sh offboard [--pr <n>] [--repo <org/app>] [--purge-ecr]
scripts/onboard-app.sh offboard --pr <n> --yes
Default: tears down the app's pr-* preview namespaces + DROPs their pr_<n>
schemas. Opt-in: --purge-ecr (delete the preview ECR repo), --repo (prints/
deletes the GitHub secret + caller workflows). Safety: dry-run unless
--yes; it only ever acts on pr-<n> namespaces (never example-app-prod,
kube-*, etc.). The org-wide OIDC trust is shared, so it is not revoked for
one repo.
Notes
- Verify a live preview the way the platform does:
curl the URL's /api/health
(200) and a real route. For browser access without DNS, use the printed
kubectl port-forward.
- Full contract + both routing modes:
docs/onboarding.md.
