Agent Skills › openai/plugins › render-blueprints

render-blueprints

GitHub

用于编写、编辑和验证 Render 基础设施即代码 (IaC) 的 render.yaml 蓝图。涵盖服务连接、项目分组、预览环境配置及字段校验，帮助用户正确定义云资源结构。

plugins/render/skills/render-blueprints/SKILL.md openai/plugins

Trigger Scenarios

render.yaml Blueprint fromDatabase fromService envVarGroups previews projects environments

Install

npx skills add openai/plugins --skill render-blueprints -g -y

More Options

Non-standard path

npx skills add https://github.com/openai/plugins/tree/main/plugins/render/skills/render-blueprints -g -y

Use without installing

npx skills use openai/plugins@render-blueprints

指定 Agent (Claude Code)

npx skills add openai/plugins --skill render-blueprints -a claude-code -g -y

安装 repo 全部 skill

npx skills add openai/plugins --all -g -y

预览 repo 内 skill

npx skills add openai/plugins --list

SKILL.md

Frontmatter

{
    "name": "render-blueprints",
    "license": "MIT",
    "metadata": {
        "author": "Render",
        "version": "1.0.0",
        "category": "configuration"
    },
    "description": "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.",
    "compatibility": "Git repository on GitHub, GitLab, or Bitbucket for Blueprint sync. Render CLI v2.7.0+ recommended for `render blueprints validate`. IDEs can validate against the public JSON Schema URL below."
}

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

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 (registry + optional registryCredential).
static: Static site; requires staticPublishPath and build output paths (see references).

Cross-Service Wiring

Env vars under envVars (and analogous patterns in groups) can pull values from other resources instead of hardcoding secrets.

`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.

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:
              - source: 0.0.0.0/0
                description: everywhere

        databases:
          - name: db
            plan: starter

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.
Environment isolation (Professional+) 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 PR previews:

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

Services can override preview behavior (e.g. service-level previews.generation). Limitations: autoscaling behavior, sync: false vars, previewPlan / flexible instance constraints—see references/preview-environments.md.

Validation

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`, `previewPlan` (previews), database `plan`
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`

Deprecated names to avoid: env (use runtime), redis (use keyvalue), autoDeploy (use autoDeployTrigger), pullRequestPreviewsEnabled (use previews.generation). Details: 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, overrides, `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

Version History

11c74d6 Current 2026-07-19 09:44

Metadata

Files: 0
Version: 11c74d6
Hash: 70ce7fae
Indexed: 2026-07-19 09:44

render-blueprints