render-deploy

name

render-deploy

description

Deploy Web Services, Private Services, Background Workers, Cron Jobs, Static Sites, PostgreSQL, and Key-Value (Redis-compatible) on Render via Blueprints (`render.yaml`) or the Render API with preview environments, zero-downtime rolling deploys, health checks, env-group secret scoping, and one-click rollback. Use when releasing services, applying schema migrations, or syncing infra-as-code on Render. Requires RENDER_API_KEY (owner- or workspace-scoped).

Render Deploy

Ship Render workloads with Blueprint-driven infra-as-code, gated migrations, zero-downtime rollouts, and verified health.

Stack Baseline (2026)

Concern	Choice	Notes
IaC	render.yaml Blueprint v1	Source of truth for services, env groups, databases, jobs
API	https://api.render.com/v1	Bearer token = RENDER_API_KEY
CLI	render CLI ≥1.x	render deploys create, render psql, render logs --tail
Service types	Web, Private, Worker, Cron, Static Site	Plus PostgreSQL & Key-Value managed datastores
Deploy strategy	Rolling (default for paid plans), health-checked	Failed health check aborts deploy
Preview environments	Auto from PRs when previews: generation: automatic in Blueprint	Ephemeral databases included
Env groups	Linked to multiple services; updated atomically	Use for shared secrets
Secrets	sync: false env vars set via dashboard/API only	Never commit values
Health check	healthCheckPath required for zero-downtime	E.g. /healthz returning 200 within 5 min
Migrations	Run as part of buildCommand or a one-off Job	Gate behind feature flags
Regions	Oregon, Ohio, Virginia, Frankfurt, Singapore (varies by plan)	Co-locate service + DB

When to Use

• Deploying new or updated Render services.
• Applying render.yaml changes (Blueprint sync).
• Spinning preview environments for PRs.
• Rolling forward / back a single service via API or CLI.
• Coordinating app deploy with database migration.

Prerequisites

• RENDER_API_KEY exported in CI (workspace-scoped least-privilege token).
• render.yaml checked in at repo root and validated.
• Service IDs (srv-...), database IDs (dpg-...), and env-group IDs (evg-...) recorded.
• Health endpoint implemented and returning 200 within startup window.
• Migration tool (Alembic, Prisma, Flyway, etc.) usable in build or job context.

Instructions

1. Validate Blueprint locally (schema lint via the API dry-run):

   curl -fsS -X POST https://api.render.com/v1/blueprints/validate \
     -H "Authorization: Bearer $RENDER_API_KEY" \
     -H "Content-Type: application/yaml" \
     --data-binary @render.yaml
   

2. Author a minimal Blueprint with health check and env group:

   # render.yaml
   previews:
     generation: automatic
     expireAfterDays: 7
   
   envVarGroups:
     - name: api-shared
       envVars:
         - key: LOG_LEVEL
           value: info
         - key: STRIPE_SECRET
           sync: false   # set via dashboard
   
   services:
     - type: web
       name: api
       runtime: node
       plan: standard
       region: oregon
       branch: main
       buildCommand: npm ci && npm run build && npm run migrate:deploy
       startCommand: node dist/server.js
       healthCheckPath: /healthz
       autoDeploy: true
       envVars:
         - fromGroup: api-shared
         - key: DATABASE_URL
           fromDatabase:
             name: api-db
             property: connectionString
   
     - type: worker
       name: api-worker
       runtime: node
       plan: starter
       buildCommand: npm ci && npm run build
       startCommand: node dist/worker.js
       envVars:
         - fromGroup: api-shared
   
   databases:
     - name: api-db
       plan: standard
       region: oregon
       postgresMajorVersion: "16"
   

3. Set non-synced secrets via API (idempotent):

   curl -fsS -X PUT https://api.render.com/v1/env-groups/$EVG_ID/env-vars \
     -H "Authorization: Bearer $RENDER_API_KEY" \
     -H "Content-Type: application/json" \
     -d '[{"key":"STRIPE_SECRET","value":"'"$STRIPE_SECRET"'"}]'
   

4. Pre-deploy checks in CI: lint, test, build, dry-run migration:

   npm ci && npm run lint && npm test && npm run build
   npm run migrate:status   # confirm pending migrations are expected
   

5. Trigger deploy via API (do not rely on auto-deploy in CI; explicit is auditable):

   DEPLOY=$(curl -fsS -X POST \
     https://api.render.com/v1/services/$SRV_ID/deploys \
     -H "Authorization: Bearer $RENDER_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"clearCache":"do_not_clear","commitId":"'"$GIT_SHA"'"}')
   DEPLOY_ID=$(echo "$DEPLOY" | jq -r .id)
   

6. Poll deploy status until live (or fail fast on build_failed / update_failed / deactivated):

   while :; do
     STATUS=$(curl -fsS -H "Authorization: Bearer $RENDER_API_KEY" \
       https://api.render.com/v1/services/$SRV_ID/deploys/$DEPLOY_ID | jq -r .status)
     echo "status=$STATUS"
     case "$STATUS" in
       live) break ;;
       build_failed|update_failed|canceled|deactivated) exit 1 ;;
     esac
     sleep 10
   done
   

7. Tail logs during rollout:

   render logs --tail --resources $SRV_ID
   

8. Smoke test production:

   curl -fsS https://api.example.com/healthz
   curl -fsS https://api.example.com/v1/ready
   

9. Rollback by re-deploying the previous commit (Render keeps deploy history):

   curl -fsS -X POST https://api.render.com/v1/services/$SRV_ID/rollback \
     -H "Authorization: Bearer $RENDER_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"deployId":"<PREV_DEPLOY_ID>"}'
   

10. Migration safety: forward-only, additive (expand-then-contract). For destructive changes, ship in N+1 release after code that no longer reads the column.

Common Pitfalls

Pitfall	Impact	Fix
No healthCheckPath set	Render assumes "live" once process binds; failed boot serves errors	Always set /healthz; return 200 only when ready
Migration in startCommand	Each instance retries; race conditions	Run in buildCommand (single execution) or a one-off job
Destructive migration shipped with the code that needs the dropped column	Outage during rolling deploy	Expand-and-contract across releases
Secrets stored with sync: true	Plaintext in Blueprint / git	Use sync: false and set via dashboard/API
Using a Render API key with full owner scope in CI	Blast radius on token leak	Workspace-scoped, least-privilege key
Service and database in different regions	Added latency, cross-region cost	Co-locate in same region
Relying on auto-deploy from main in CI	Drift between commit and what was actually deployed	Explicit API deploy with commitId
Long-running cron in a Web Service	Blocks request handlers	Use Cron Job service type
Ignoring clearCache after dependency upgrade	Stale build artifacts	Use "clearCache":"clear" once
Not gating preview environments	Surprise costs from many PRs	expireAfterDays + plan caps

Output Format

Report to caller:

1. Deploy ID, commit SHA, service ID, environment.
2. Status timeline (build_in_progress → update_in_progress → live) with timestamps.
3. Migration result (applied versions, skipped, none).
4. Health-check + smoke-test outcomes.
5. Pre-filled rollback curl with previous deploy ID.

Authoritative References

• Render Blueprint spec: https://render.com/docs/blueprint-spec
• Render REST API: https://api-docs.render.com/reference/introduction
• Zero-downtime deploys & health checks: https://render.com/docs/deploys#zero-downtime-deploys
• Preview environments: https://render.com/docs/preview-environments
• Env groups: https://render.com/docs/configure-environment-variables#environment-groups
• Rolling back a deploy: https://render.com/docs/rollbacks
• Render CLI: https://render.com/docs/cli