# Render Blueprints

> Authors and validates render.yaml Blueprints for Render infrastructure. Use when the user needs to write or edit a render.yaml, wire services together with fromDatabase/fromService/fromGroup, set up projects and environments for multi-service apps, configure preview environments, validate against the schema, or fix immutable field errors. Trigger terms: render.yaml, Blueprint, IaC, fromDatabase, fromService, envVarGroups, previews, projects, environments.

- Skill: `render-oss/render-blueprints` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds add render-oss/render-blueprints`
- Raw SKILL.md: https://api.skillmd.com/api/skills/render-oss/render-blueprints/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: render-oss (https://skillmd.com/u/render-oss)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/render-oss/render-blueprints

---


# Render Blueprints (render.yaml)

Blueprints define Render infrastructure as YAML (commonly `render.yaml` at the repo root). This skill focuses on **authoring**, **wiring**, **projects/environments**, **previews**, **validation**, and **immutable fields**. Heavy detail lives under `references/`.

## When to Use

Apply this skill when the user:

- Creates or edits a `render.yaml` / Blueprint
- Wires databases, private services, or Key Value into app env vars
- Groups services with **projects** and **environments**
- Configures **preview environments** for pull requests
- Validates YAML against Render’s schema or CLI
- Asks what can or cannot change after a resource is created

For end-to-end deploy flows and MCP/CLI operations, see **render-deploy**. For env var strategy outside Blueprint syntax, see **render-env-vars**. For Docker-specific Blueprint fields, see **render-docker**.

## Blueprint Structure

### Top-level keys

| Key | Purpose |
|-----|---------|
| `services` | Web, worker, cron, private service, Key Value, static (via `web` + `runtime: static`) |
| `databases` | Managed PostgreSQL instances |
| `envVarGroups` | Reusable env var sets attached to services |
| `projects` | Optional grouping; contains `environments` and service lists |
| `previews` | Defaults for PR preview environments |

A Blueprint may also use patterns like **ungrouped** resources vs **environment-scoped** lists, depending on whether you adopt the projects model. Avoid duplicating the same logical resource in multiple places (see `references/common-mistakes.md`).

### Schema and IDE validation

- **JSON Schema URL:** `https://render.com/schema/render.yaml.json`
- Configure your editor to associate `render.yaml` with that schema for completions and diagnostics.

### Minimal example: web + PostgreSQL

```yaml
databases:
  - name: mydb
    plan: basic-256mb
    region: oregon

services:
  - type: web
    name: api
    runtime: node
    region: oregon
    plan: starter
    buildCommand: npm ci && npm run build
    startCommand: npm start
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: mydb
          property: connectionString
```

## Service Types

| `type` | Role |
|--------|------|
| `web` | Public HTTP service (use `runtime: static` for static sites) |
| `pserv` | Private service (internal HTTP/TCP; not public) |
| `worker` | Long-running background process |
| `cron` | Scheduled job (`schedule` required) |
| `keyvalue` | Managed Key Value (Redis-compatible); alias **`redis`** accepted in Blueprints |

## Runtimes

Common `runtime` values: **`node`**, **`python`**, **`go`**, **`ruby`**, **`rust`**, **`elixir`**, **`docker`**, **`image`**, **`static`**.

- **`docker`**: Build from `Dockerfile` (see `dockerfilePath`, `dockerContext`, `dockerCommand`).
- **`image`**: Run a prebuilt container image with `image.url` and optional `image.creds.fromRegistryCreds`.
- **`static`**: Static site; requires `staticPublishPath` and build output paths (see references).

## Cross-Service Wiring

Service env vars under `envVars` can pull values from other resources instead of hardcoding secrets. Environment-group variables cannot reference services, databases, or other environment groups.

### `fromDatabase`

Reference a database in `databases:` by `name`. Properties include:

- `connectionString`, `host`, `port`, `user`, `password`, `database`

### `fromService`

Reference a service by `name`. Typical properties:

- `host`, `port`, `hostport`, `connectionString`, `envVarKey`

Which properties are valid depends on target service type (e.g. Key Value vs `pserv`). See `references/wiring-patterns.md`.

### `fromGroup`

Attach shared vars from `envVarGroups` (by group `name`).

### Other env var keys

- **`value`**: Literal string.
- **`generateValue`**: Let Render generate a random secret (password/API key).
- **`sync`**: Set `sync: false` for secrets that should not sync from repo on every update (see edge cases in wiring reference).

Full patterns and combinations: `references/wiring-patterns.md`.

## Projects and Environments

For multi-service apps, use the **`projects`/`environments`** pattern instead of flat top-level `services`/`databases`. This groups all related resources into a single Render project, supports multiple environments (production, staging), and enables environment-scoped configuration.

```yaml
projects:
  - name: my-app
    environments:
      - name: production
        services:
          - type: web
            name: api
            runtime: node
            plan: standard
            buildCommand: npm ci && npm run build
            startCommand: npm start
            envVars:
              - key: DATABASE_URL
                fromDatabase:
                  name: db
                  property: connectionString
              - key: REDIS_URL
                fromService:
                  type: keyvalue
                  name: cache
                  property: connectionString
              - key: API_SECRET
                sync: false

          - type: worker
            name: jobs
            runtime: node
            plan: starter
            buildCommand: npm ci
            startCommand: node worker.js
            envVars:
              - key: DATABASE_URL
                fromDatabase:
                  name: db
                  property: connectionString
              - key: REDIS_URL
                fromService:
                  type: keyvalue
                  name: cache
                  property: connectionString

          - type: keyvalue
            name: cache
            plan: starter
            maxmemoryPolicy: noeviction
            ipAllowList: [] # Internal access only

        databases:
          - name: db
            plan: basic-256mb
```

Key rules:

- Each environment owns its `services` and `databases` lists.
- Do not define the same resource at both the root level and inside an environment.
- `envVarGroups` can be scoped to a project environment or shared across the workspace.
- With a Pro workspace or higher, environment isolation can block cross-environment private network traffic.

For single-service apps, flat top-level `services`/`databases` is fine. Reach for the projects pattern when you have multiple services, need staging/production separation, or want environment-scoped env groups.

## Preview Environments

Top-level `previews` controls Blueprint preview environments:

- **`previews.generation`**: `off` (default), `manual`, or `automatic`
- **`previews.expireAfterDays`**: Auto-delete preview stacks after N days

Do not confuse preview environments with service previews. A service-level `previews.generation` setting controls that service's independent pull request previews and does **not** override preview-environment generation; it accepts only `manual` or `automatic`, and omission disables service previews. Within the same service-level object, `previews.plan` and `previews.numInstances` size the service in preview environments. Key Value and Postgres use `previewPlan` instead. Limitations: autoscaling behavior, `sync: false` vars, and flexible database instance constraints—see `references/preview-environments.md`.

## Validation

```bash
render blueprints validate
```

Requires **Render CLI v2.7.0+**. Run from the repo root (or pass the appropriate path options your CLI version supports). Fix schema and semantic errors before merging Blueprint changes.

Official schema: `https://render.com/schema/render.yaml.json`

## Immutable Fields

**CRITICAL:** Some fields cannot change after the resource is created. Edits may be rejected or require replacement resources.

### Services

- **`type`**: Cannot change (e.g. web → worker).
- **`runtime`**: Cannot change (e.g. node → docker).

### Databases

Cannot change after creation:

- `name` (logical Blueprint/database identifier in this context)
- `databaseName`
- `user`
- `region`
- `postgresMajorVersion`

Plan other fields (disk, HA, replicas) carefully up front; consult Render docs for fields that can scale vs require recreation.

## Key Fields (Quick Map)

| Area | Fields |
|------|--------|
| Plans | `plan`; compute-service `previews.plan`; Key Value/Postgres `previewPlan` |
| Build/run | `buildCommand`, `startCommand`, `preDeployCommand`, `rootDir` |
| Deploy | `autoDeployTrigger`: `commit`, `checksPass`, or `off` |
| Lifecycle | `maxShutdownDelaySeconds`: 1–300, default **30** |
| HTTP | `healthCheckPath`, `domains` |
| Storage | `disk` (`name`, `mountPath`, `sizeGB`) |
| Scale | `scaling` / `numInstances` (see references) |
| Monorepo | `buildFilter` (`paths`, `ignoredPaths`) |
| Docker | `dockerfilePath`, `dockerContext`, `dockerCommand`, `registryCredential`; prebuilt `image.url` / `image.creds` |

Deprecated names to avoid: `env` (use `runtime`), `redis` (use `keyvalue`), `autoDeploy` (use `autoDeployTrigger`), `previewsEnabled`, and `pullRequestPreviewsEnabled`. Use the appropriate top-level or service-level `previews.generation` replacement described in `references/common-mistakes.md`.

## References

| Document | Contents |
|----------|----------|
| `references/field-reference.md` | YAML fields by service type, database, groups, projects, previews, scaling, disk, static, Key Value |
| `references/wiring-patterns.md` | `fromDatabase` / `fromService` / `fromGroup` examples, `sync: false`, `generateValue`, combinations |
| `references/common-mistakes.md` | Branch + previews, `buildFilter`, replicas, duplicates, preview plans, wiring mistakes |
| `references/preview-environments.md` | `previews.generation`, expiry, `previews.plan`, `previewPlan`, disks, PR workflow |

## Related Skills

- **render-deploy** — Deploy flows, Blueprint vs direct create, MCP/deeplinks
- **render-env-vars** — Env var strategy, secrets, Dashboard vs Blueprint
- **render-docker** — Dockerfile-backed services and image runtime nuances