Deployment

DevStride uses Pulumi for infrastructure-as-code and GitHub Actions for CI/CD. The ds deploy commands orchestrate both, giving you a simple interface for managing cloud environments.

Deploying a Stage

Basic Deploy

ds deploy up

Dispatches a GitHub Actions workflow that:

1. Builds the frontend (Vite)
2. Bundles Lambda functions (esbuild)
3. Runs pulumi up to create/update AWS resources
4. Uploads the frontend build to S3
5. Invalidates the CloudFront cache
6. Outputs your API and UI URLs

The CLI streams the workflow logs to your terminal in real time.

Specifying Options

# Deploy a specific branch
ds deploy up feature/auth-improvements

# Specify the stage name explicitly
ds deploy up --stage phil-auth

# Specify the branch explicitly
ds deploy up --branch feature/auth-improvements

# Custom DNS label (the final stage identifier in URLs)
ds deploy up --route phil-auth-v2

# Allow creating a second stack when one already exists for this branch
ds deploy up --new-stack

How cloud stage names are resolved:

1. If --stage is provided, use it directly.
2. If --branch (or positional argument) is provided, compute stage from {developer}-{branch}.
3. If neither is provided, the CLI prompts you interactively.

What Gets Deployed

A full stage includes approximately 50 AWS resources:

Deploy Timing

Tearing Down a Stage

Basic Teardown

ds deploy down phil-feature-auth

If you omit the stage name, the CLI prompts you to select one.

What Gets Cleaned Up

The teardown is thorough:

1. S3 buckets are emptied (required before deletion)
2. pulumi destroy removes all AWS resources
3. Secrets Manager entries for this stage are deleted
4. Neon database branch is kept by default — use --delete-neon to also remove it
5. Pulumi stack state is removed (unless --keep-stack)
6. Local files are cleaned: bind cache, setup state, config files, shell config entries

Options

Safety Confirmation

Teardown requires you to type the stage name to confirm:

This will destroy ALL resources for stage 'phil-feature-auth'.
Type the stage name to confirm: phil-feature-auth

Listing Deployed Stages

List All Stages

ds deploy list

Shows a table of all deployed Pulumi stages with:

• Stage name and region
• API and UI URLs
• Creation date and last activity
• Resource counts

Detailed View

ds deploy list --stage phil-local

Shows expanded details for a single stage:

• Cognito user pool ID and client ID
• DynamoDB table names
• Step Functions state machine ARN
• S3 bucket name
• CloudFront distribution ID

Options

Frontend-Only Deploy

When you only changed frontend code and don't want to wait for a full pulumi up, deploy just the UI:

# Build + sync to S3 + invalidate CloudFront (~60 seconds)
ds deploy frontend [stage]

# Skip rebuild — sync an existing dist/ folder
ds deploy frontend [stage] --skip-build

This is purely local — no GitHub Actions, no Pulumi. It requires infrastructure to already be deployed (ds deploy up must have run at least once). Useful for rapid UI iteration on a cloud stage.

Reconciling Pulumi State (Drift Fix)

If AWS resources were deleted or modified outside of Pulumi (via the AWS console, a partial failed deploy, or manual cleanup), pulumi up will fail with resource conflicts. Fix this with:

ds deploy refresh

This runs pulumi refresh to sync Pulumi's state file with the real AWS state. It only reads from AWS — it never modifies or deletes resources. After a refresh, re-run ds deploy up to bring the stage back to the desired state.

URL Patterns

Deployed stages follow predictable URL patterns:

Protected stages (dev, prod) use bare domains. Personal stages are prefixed with the stage name. Your local stage (phil-local) has the same URL structure as cloud stages.

Deployment Workflow Details

Under the hood, ds deploy up uses the GitHub API to dispatch a workflow:

ds deploy up
    │
    ├── Resolves stage name and branch
    ├── Validates AWS credentials (re-auth if needed)
    ├── Dispatches deploy-stage.yml via gh api
    ├── Streams workflow logs to terminal
    │
    └── GitHub Actions (deploy-stage.yml):
        ├── Checkout code
        ├── pnpm install
        ├── Build frontend (Vite)
        ├── Bundle Lambdas (esbuild)
        ├── pulumi up (infrastructure)
        ├── Upload frontend to S3
        ├── Invalidate CloudFront
        └── Output URLs

Troubleshooting

Deploy hangs or fails

Check the GitHub Actions workflow run directly:

gh run list --workflow=deploy-stage.yml --limit=5
gh run view <run-id> --log

"Stack already exists"

Your stage already has a Pulumi stack. This is normal for subsequent deploys — Pulumi updates in place. If you specifically need a second stack for the same branch, use --new-stack.

"S3 bucket not empty"

This can happen during deploy down. The CLI should handle this automatically by emptying buckets first. If it fails, manually empty the bucket in the AWS console, then re-run deploy down.

Resource conflicts between stages

Each stage has fully isolated resources (different names, different ARNs). If you see conflicts, it usually means the stage name collision — check ds deploy list for duplicate stage names.

Next Steps

• Database Management — Managing your database alongside deployments
• AWS Operations — Cleaning up orphaned resources
• Developer Lifecycle — End-to-end workflow examples