How It Works

Smart Deploy connects your GitHub repo to AWS through a predictable pipeline: scan → preview → deploy → monitor.

flowchart LR
  A[Connect GitHub] --> B[Detect services]
  B --> C[Smart Analysis]
  C --> D[Blueprint preview]
  D --> E{Plan OK?}
  E -->|Edit| D
  E -->|Yes| F[Deploy]
  F --> G[Logs and health]

Components you interact with

Piece	What it does for you
Dashboard	Lists repos and deployments
Repo page	Service catalog, scan, and deploy workspace per repo
Blueprint	Visual preview of the full deploy path
Deploy workspace	Live logs, overview, history, and config while deploying or running
Deployment Agent	Read-only AI that inspects your deployments via tools

Behind the scenes

Component	Role
SD Artifacts	Scans repos, generates Railpack plans, verifies builds, supports improve-scan feedback
WebSocket worker	Runs long deploy jobs, streams logs, reconciles runtime health
AWS	CodeBuild, ECR, ECS Fargate, ALB, Route 53, S3, CloudFront, Secrets Manager, CloudWatch
Database	Stores deployments, scan results, history, and agent conversations

You do not configure these primitives directly — Smart Deploy orchestrates them from your repo scan and deployment config.

Scan → plan

Service detection discovers deployable units (monorepo packages, compose dirs, Dockerfiles, root apps).
Smart Analysis clones your repo at a commit and runs SD Artifacts:
- Classifies deploy shape (server, static, static_build, multi, existing_docker)
- Generates Railpack plans (or uses your Dockerfile)
- Optionally verifies the build and attempts repair
Results are stored and linked to your deployment as the source of truth for preview and deploy.

See Smart Analysis and Railpack.

Preview → configure

The blueprint turns scan results into a five-step pipeline you can read and edit:

Auth and resolve ref (repo, branch, commit)
Build (deploy units, CodeBuild output)
Setup (region, networking or static bucket)
Deploy (env vars, routing, secrets)
Done (hosted URL)

See Blueprint and Preview.

Deploy → release

When you deploy, the WebSocket worker runs the pipeline:

Container path: CodeBuild → ECR → ECS Fargate → ALB host rule → Route 53 → HTTP verification
Static path: CodeBuild → S3 sync → optional CloudFront invalidation

Logs stream to the UI in real time. Each attempt is recorded in deployment history.

See Deployment Pipeline.

Monitor → debug

After deploy:

Runtime health probes your URL and ECS/ALB signals on a schedule
Deployment history keeps every attempt with step logs and failure classification
Deployment Agent can list deployments, load details, history, and health on demand

See Runtime Health and Debugging Deployments.

Deploy routing (ECS vs static S3)

Scan signal	Target
`deploy_shape: static`	S3
`deploy_shape: static_build` with no Railpack start command	S3
`deploy_shape: server`, `multi`, `existing_docker`, or static with runtime	ECS Fargate

Railpack's deploy.startCommand is the key fork for static_build — build-only SPAs go to S3; apps that serve built assets at runtime go to ECS.

Repository docs

Rendered document