How Deploys Work
Render makes deploying your application as easy as pushing your code to source control.
Automatic Git deploys
By default, Render automatically deploys a Git-backed service (any service connected to a GitHub/GitLab/Bitbucket repo) whenever changes are pushed or merged to the service’s linked branch.
Render does not automatically deploy image-backed services (services that pull a Docker image from a container registry). See details.
You can skip an auto-deploy for a particular commit, or even disable auto-deploys entirely for your service.
Skipping an auto-deploy
Certain changes to your codebase might not merit a new deploy, such as edits to a README
file. In these cases, you can include a skip phrase in your Git commit message to prevent the change from triggering an auto-deploy:
git commit -m "[skip render] Update README"
The skip phrase is one of [skip render]
or [render skip]
. You can also use one of the following in place of render
:
deploy
cd
When an auto-deploy is skipped, a corresponding entry appears on your service’s Events page:
If you configure build filters for your repo, Render deploys your service only if there are changes to particular files. This method of skipping an auto-deploy doesn’t require a skip phrase. See Specifying Build Filters.
Disabling auto-deploys
If you always want to trigger deploys manually, you can disable auto-deploys in the Render Dashboard:
-
Go to your service’s Settings page and set Auto-Deploy to No:
-
Click Save changes.
Deploy steps
With each deploy, Render proceeds through the following commands for your service:
*Consumes pipeline minutes while running. View your usage.
You specify these commands as part of creating your service in the Render Dashboard. You can modify these commands for an existing service from its Settings page:
Each command is described below.
If any command fails or times out, the entire deploy fails. Any remaining commands do not run. Your service continues running its most recent successful deploy (if any), with zero downtime.
Command timeouts are as follows:
Command | Timeout |
---|---|
Build | 120 minutes |
Pre-deploy | 30 minutes |
Start | 15 minutes |
Build command
Performs all compilation and dependency installation that’s necessary for your service to run. It usually resembles the command you use to build your project locally.
This command consumes pipeline minutes while running. You receive a free allotment of pipeline minutes each month and can purchase more as needed. View your usage.
Example build commands for each runtime
Runtime | Example Build Command(s) |
---|---|
Node.js | yarn , npm install |
Python | pip install -r requirements.txt |
Ruby | bundle install |
Go | go build -tags netgo -ldflags '-s -w' -o app |
Rust | cargo build --release |
Elixir | mix phx.digest |
Docker | You can’t set a build command for services that use Docker. Instead, Render either builds a custom image based on your Dockerfile or pulls a specified image from your container registry. |
Pre-deploy command
If defined, the pre-deploy command runs after your service’s build finishes, but before that build is deployed. Recommended for tasks that should always precede a deploy but are not tied to building your code, such as:
- Database migrations
- Uploading assets to a CDN
The pre-deploy command executes in a different environment from your running service.
Changes you make to the filesystem are not reflected in the deployed service. You do not have access to a service’s attached persistent disk (if it has one).
The pre-deploy command is available for paid web services, private services, and background workers.
If you don’t define a pre-deploy command for a service, Render proceeds directly from the build command to the start command.
This command consumes pipeline minutes while running. You receive a free allotment of pipeline minutes each month and can purchase more as needed. View your usage.
Start command
Render runs this command to start your service when it’s ready to deploy.
Example start commands for each runtime
Runtime | Example Start Command(s) |
---|---|
Node.js | yarn start , npm start , node index.js |
Python | gunicorn your_application.wsgi |
Ruby | bundle exec puma |
Go | ./app |
Rust | cargo run --release |
Elixir | mix phx.server |
Docker | By default, Render runs the CMD defined in your Dockerfile. You can specify a different command in the Docker Command field on your service’s Settings page. |
Managing deploys
Canceling a deploy
You can cancel an in-progress deploy in the Render Dashboard:
-
Go to your service’s Events page and click the word Deploy in the corresponding event entry.
- This opens the deploy’s details page.
-
Click Cancel deploy:
Restarting a service
If your service is misbehaving, you can restart it from the service’s page in the Render Dashboard. Click Manual Deploy > Restart service:
Note the following about restarting a service:
- When you restart your service, Render actually deploys a completely new instance and swaps over to it when it’s ready. The original running instance is then deprovisioned.
- This makes restarting a zero-downtime action, similar to other deploys.
- If you restart a scaled service, Render performs a restart for every instance.
- If you restart a service, the new instance uses the same configuration as the original instance, including values of environment variables.
- This means that if you’ve recently updated your service’s configuration but haven’t redeployed since then, restarting will not cause your service to incorporate those updates.
Health checks
Health checks are currently available only for web services.
You can (and should!) define a health check endpoint for every web service to help Render determine whether it’s ready to receive traffic. Render sends an HTTP request to this endpoint as part of zero-downtime deploys, and also every few seconds to verify the health of running services.
Set your health check endpoint path in the Render Dashboard from your web service’s Settings page:
If you manage your service with a Blueprint, instead set the healthCheckPath
field in your render.yaml
file.
Health check protocol
With every health check, Render sends an HTTP GET
request to each service instance’s health check endpoint. If your service has at least one custom domain, Render sets one of those domains as the value of the Host
header for the request. Otherwise, Render uses the service’s onrender.com
subdomain.
- The check succeeds if your health check endpoint responds with a
2xx
or3xx
status code. Render considers the instance healthy. - The check fails in all other cases (including after a 5-second response timeout). Render considers the instance potentially unhealthy.
If a potentially unhealthy instance continues to fail its health checks, Render takes the following actions:
- During a zero-downtime deploy:
- If a new instance fails all of its health checks for 15 consecutive minutes, Render cancels the deploy and continues routing traffic to existing instances.
- For an actively running service:
- If an instance fails all of its health checks for 15 consecutive seconds, Render stops routing traffic to it to give it an opportunity to recover.
- After 60 consecutive seconds of failed health checks, Render automatically restarts the service.
In the event of a canceled deploy or a service restart, Render notifies you according to your settings.
The actions your endpoint should take to verify service health depend on your service’s details. We recommend performing operation-critical checks, such as executing a simple database query to confirm connectivity.
Deployment concepts
Ephemeral filesystem
By default, Render services have an ephemeral filesystem. This means that any changes a running service makes to its filesystem are lost with each deploy.
To persist data across deploys, do one of the following:
- Create and connect to a Render-managed datastore (PostgreSQL or Redis).
- Create and connect to a custom datastore, such as MySQL or MongoDB.
- Attach a persistent disk to your service.
- Note the limitations of persistent disks.
Zero-downtime deploys
Whenever you deploy a new version of your service, Render performs a sequence of steps to make sure the service stays up and available throughout the deploy process—even if the deploy fails.
This zero-downtime deploy sequence applies to web services, private services, background workers, and cron jobs. Static sites also update with zero downtime, but they’re backed by a CDN and don’t involve service instances. Learn more about service types.
Adding a persistent disk to your service disables zero-downtime deploys for it. See details.
Sequence of events
-
When you push up a new version of your code, Render attempts to build it.
- If the build fails, Render cancels the deploy, and your original service instance continues running without interruption.
-
If the build succeeds, Render attempts to spin up a new instance of your service running the new version of your code.
- For web services and private services, your original instance continues to receive all incoming traffic while the new instance is spinning up:
-
If the new instance spins up successfully (for web services, you can help verify this by setting up health checks), Render updates your current deployed commit accordingly.
- For web services and private services, Render also updates its networking configuration so that your new instance begins receiving all incoming traffic:
-
After 60 seconds, Render sends a
SIGTERM
signal to your app’s process on the original instance.- This signals your app to initiate a graceful shutdown.
-
If your app’s process doesn’t exit within a 30-second grace period after receiving the
SIGTERM
signal, Render sends aSIGKILL
signal to force the process to terminate.-
If you manage your service with a Blueprint, you can extend this grace period by setting the
maxShutdownDelaySeconds
field in yourrender.yaml
file.
-
-
The zero-downtime deploy is complete.
For services that are scaled to multiple instances, Render performs steps 2-5 for one instance at a time. If any new instance fails to become healthy during this process, Render cancels the entire deploy and reverts to instances running the previous version of your service.