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	Real-time UI, Deployment Agent, runtime health, and live log relay from deploy tasks
Deployment queue	SQS FIFO queue that orders and buffers deploy runs before execution
Deployment launcher	Lambda function that reads the queue and starts one ECS task per run
Deployment runner	Short-lived ECS Fargate task that runs the deploy pipeline
AWS	SQS, Lambda, 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 creates a deployment run and enqueues it on SQS (FIFO, grouped per user/repo/service).
A Lambda handler consumes the message and launches a one-off ECS Fargate task (deployment runner).
The runner executes the pipeline:
- Container path: CodeBuild → ECR → ECS Fargate → ALB host rule → Route 53 → HTTP verification
- Static path: CodeBuild → S3 sync → optional CloudFront invalidation
Live logs POST back to the WebSocket worker and stream to the UI. Each attempt is recorded in deployment history.

flowchart LR
  UI[Deploy workspace] --> WS[WebSocket worker]
  WS --> SQS[SQS FIFO]
  SQS --> Lambda[Lambda]
  Lambda --> Runner[ECS deployment runner]
  Runner --> AWS[Target AWS resources]
  Runner -->|events| WS
  WS --> UI

Platform operators provision the queue, Lambda, and deployment worker with infra/smart-deploy-platform.

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