YAML Specification

Here’s a sample YAML file that uses most of the supported settings for infrastructure as code. Use it to get started with your own render.yaml.

Make sure to place render.yaml at the root of your repository.
# A Docker web service
- type: web
  name: webdis
  env: docker
  repo: https://github.com/render-examples/webdis.git # optional
  plan: standard              # optional
  branch: master              # optional (uses repo default)
  healthCheckPath: /
  - key: REDIS_HOST
      name: redis
      type: pserv
      property: host          # available properties are listed below
  - key: REDIS_PORT
      name: redis
      type: pserv
      property: port
  - fromGroup: conc-settings
# A private Redis instance
- type: pserv
  name: redis
  env: docker
  repo: https://github.com/render-examples/redis.git # optional
    generateValue: true       # will generate a base64-encoded 256-bit secret
    sync: false               # placeholder for a value to be added in the dashboard
    name: redis-data
    mountPath: /var/lib/redis
    sizeGB: 10                # optional
# A Ruby web service
- type: web
  name: sinatra
  env: ruby
  repo: https://github.com/renderinc/sinatra-example.git
  numInstances: 3
  buildCommand: bundle install
  startCommand: bundle exec ruby main.rb
  - test0.render.com
  - test1.render.com
    value: Z2V0IG91dHRhIGhlcmUhCg
  - key: DB_URL
      name: elephant
      property: connectionString
      type: pserv
      name: redis
  autoDeploy: false             # optional
# A Python cron job that runs every hour
- type: cron
  name: date
  env: python
  schedule: "0 * * * *"
  buildCommand: "true"        # ensure it's a string
  startCommand: date
  repo: https://github.com/render-examples/docker.git # optional
# A background worker that consumes a queue
- type: worker
  name: queue
  env: docker
  dockerfilePath: ./sub/Dockerfile # optional
  dockerContext: ./sub/src    # optional
  branch: queue               # optional
# A static site
- type: web
  name: my blog
  env: static
  buildCommand: yarn build
  staticPublishPath: ./build
  pullRequestPreviewsEnabled: true     # optional
  - path: /*
    name: X-Frame-Options
    value: sameorigin
  - type: redirect
    source: /old
    destination: /new
  - type: rewrite
    source: /a/*
    destination: /a

- name: elephant
  databaseName: mydb          # optional (Render may add a suffix)
  user: adrian                # optional

- name: conc-settings
    value: 2
  - key: SECRET
    generateValue: true
    sync: false
- name: stripe
    value: https://api.stripe.com/v2


You can define services in your YAML file.

  • Each service should have a type, name, and env.
  • Cron jobs must have a schedule.
  • Each service should have a startCommand unless it’s a Docker service in which case Render uses the command in your Dockerfile.

Repo & Branch

Services in render.yaml can omit a repo. If a repo is missing, it is assumed to be the repo the YAML file is in. The specified repo must be accessible to you.

You can also omit a branch. Render will use the repo’s default branch if it’s omitted.


The service type must be one of the following:

  • web for a web service
  • worker for a background worker
  • pserv for a private service
  • cron for a cron job
A static site is not considered a service type. It is a web service with a static environment.


The service environment must be one of the following:

  • docker
  • elixir
  • go
  • node
  • python
  • ruby
  • rust
  • static

Environment Variables

A service can specify zero or more environment variables. These variables can be plain variables as follows:

key: A
value: B

They can depend on the properties of other Render resources like databases:

key: DB_URL
  name: prod
  property: connectionString

The set of available properties is defined below.

You can pull copy environment variables from other services with a different key:

  name: mysql
  type: pserv
  envVarKey: PASSWORD

The value of an environment variable can also be generated (only if the key doesn’t already exist).

generateValue: true

There are some environment variables which you don’t want to include in your YAML file and are not generated such as external secrets. For those, you can specify a placeholder environment variable with sync: false. This allows you to declare that an environment variable is expected without having to specify a value in your YAML file.

sync: false

Environment variables can also be set all at once from an environment group:

fromGroup: my-env-group

Properties Available to Environment Variables

Environment variables can refer to the following properties on databases:

  • host
  • port
  • database is the PostgreSQL database name (not the friendly name)
  • user
  • password
  • connectionString

Environment variables can refer to the following properties on services:

  • host
  • port
  • hostport is the service’s host and port separated by a colon, as in host:port

When depending on other services, you must include the type and name of the target service. The service does not need to be in the YAML file. If it’s not in the YAML file, it must already exist in your Render account.

Here’s an example of an environment variable referring to a service property:

  name: redis
  type: pserv
  property: host
render.yaml does not support variable interpolation. The best way to accomplish this is to pair environment variables with a build or start script that does the interpolation for you.


You can specify whether your service has a Disk attached to it. A disk must have a name, mountPath, and (optionally) a size in GB (sizeGB).

  name: redis-data
  mountPath: /opt/redis
  sizeGB: 10

Custom Domains

You can specify custom domains for your service in the domains field. If a domain is an apex domain, a www. subdomain will be added automatically and will redirect to the apex domain.

If a domain is a www. subdomain, the apex domain will be added automatically and will redirect to the www. domain.

Every web service is always accessible at its .onrender.com subdomain.

Static Site Headers

You can specify HTTP headers for your static site with the headers field like you can in the dashboard.

# add X-Frame-Options: sameorigin to all paths
- path: /*
  name: X-Frame-Options
  value: sameorigin
# add Cache-Control: must-revalidate to /blog paths
- path: /blog/*
  name: Cache-Control
  value: must-revalidate

Static Site Routes

You can specify redirect and rewrite routes for your static site with the routes field just like in the dashboard.

# redirect (HTTP status 301) from /a to /b
- type: redirect
  source: /a
  destination: /b
# rewrite /app/* requests to /app
- type: rewrite
  source: /app/*
  destination: /app


The service plan can be specified by name and is case insensitive. If it’s omitted, the plan will default to the “Starter” plan. The following values are valid for plans:

  • Starter
  • Standard
  • Standard Plus
  • Pro
  • Pro Plus

Health Check Path

You can set a health check path for your HTTP service for zero downtime deploys by adding the healthCheckPath field.

healthCheckPath: /healthz

Number of Instances

You can set the number of instances you want for your service by setting the numInstances field.

numInstances: 3
Services with disks cannot be scaled up yet.

Docker Options

If your service is Docker-based, i.e. it has env: docker, then you can optionally specify the dockerfilePath and dockerContext. These are relative to your repo root. This is useful for mono-repo Docker services.

dockerfilePath: ./sub/Dockerfile
dockerContext: ./sub/src


You can create databases by defining them in render.yaml. A database only needs a name — all other fields are optional.

You can also set the PostgreSQL databaseName, user, and plan. The following two database specifications are both valid:

# db 1
- name: staging
# db 2
- name: prod
  plan: pro
  databaseName: prod_app
  user: app_user
Just like the dashboard, once a database is created, you can only change the plan it's on. Other `render.yaml` changes to database fields for an existing database will be ignored.
Also like the dashboard, Render may add a random suffix to a given databaseName.

Environment Groups

You can define environment groups in your YAML file.

  • Environment groups can have zero or more environment variables.
  • The environment variables in an environment group cannot depend on other resources, unlike the environment variables in a service. However, you can still generate environment variables within an environment group. The following is a valid environment group spec:
- name: conc-settings
    value: 2
  - key: SECRET
    generateValue: true
    sync: false