Deploying on Render

Render can automatically deploy your application each time you merge a change to your codebase:

You can also trigger manual deploys, both programmatically and in the Render Dashboard.

All service types redeploy with zero downtime, unless they attach a persistent disk.

You can view your service's deploy history and current live deploy from its Deploys page in the Render Dashboard.

Automatic deploys

As part of creating a service on Render, you link a branch of your Git provider repo (such as main or production). Whenever you push or merge a change to that branch, by default Render automatically rebuilds and redeploys your service.

Auto-deploys appear on your service's Deploys page in the Render Dashboard:

If needed, you can skip an auto-deploy for a particular commit, or even disable auto-deploys entirely.

Auto-deploys require a connected Git provider. Services that use a prebuilt Docker image or a public Git repository URL must be deployed manually.

Configuring auto-deploys

Configure a service's auto-deploy behavior from its Settings page in the Render Dashboard:

Under Auto-Deploy, select one of the following:

Integrating with CI

If you set your service's auto-deploy behavior to After CI Checks Pass, Render waits for a new commit's CI checks to complete before triggering a deploy. If all checks pass, Render proceeds with the deploy.

For GitHub checks, Render considers a check "passed" if its conclusion is any of success, neutral, or skipped.

Render does not trigger a deploy if:

• Zero checks are detected for the new commit
• At least one CI check fails for the new commit

If your repo doesn't run CI checks, use On Commit instead of After CI Checks Pass to enable auto-deploys.

Select the tab for your Git provider to learn which CI checks are supported:

Skipping an auto-deploy

Certain changes to your codebase might not require 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:

The skip phrase is one of [skip render] or [render skip]. You can also replace render with one of the following:

• deploy
• cd

When an auto-deploy is skipped, a corresponding entry appears on your service's Events page:

For additional control over auto-deploys, configure build filters.

With build filters, Render triggers an auto-deploy only if there are changes to particular files in your repo (no skip phrase required). See details.

Manual deploys

You can manually trigger a Render service deploy in a variety of ways:

Deploying a specific commit

When deploying manually, you can optionally specify a commit SHA. If you do, Render builds and deploys the specified commit instead of the latest commit from your service's linked branch.

If you deploy a specific commit SHA, you should also disable automatic deploys for your service.

Some deploy methods do this for you automatically. For details, see Effect on automatic deploys.

Learn how to provide a commit SHA using each deploy method:

Effect on automatic deploys

In almost all cases when you deploy a specific commit for your service, you should also disable automatic deploys for it. This is because automatic deploys always use the most recent commit from your service's linked branch, replacing the commit you had just deployed.

Some deploy methods disable automatic deploys for you when you provide a commit SHA:

If you deploy a specific commit with the Render CLI or API, you can disable automatic deploys in the Render Dashboard (see Configuring auto-deploys), or with a follow-up action using the same tool (see the tabs above).

If you later reenable automatic deploys for your service, Render once again deploys the most recent commit from your linked branch.

Deploy steps

With each deploy, Render proceeds through the following commands for your service:

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:

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 an included amount of pipeline minutes each month and can purchase more as needed. View your usage.

Example build commands for each runtime

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 on a separate instance 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 an included amount 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

Managing deploys

Handling overlapping deploys

Only one deploy can run at a time per service. Sometimes, a deploy will trigger while another deploy is still in progress. When this occurs, your service can do one of the following:

You can set which of these policies to use for your workspace:

1. In the Render Dashboard, open your workspace's Settings page.

2. Scroll down to the Overlapping Deploy Policy section and click Edit:

   

3. Select an option and click Save changes.

Canceling a deploy

You can cancel an in-progress deploy in the Render Dashboard by going to your service's Deploys page and clicking Cancel deploy:

If you cancel an in-progress deploy while another deploy is waiting, Render immediately kicks off the waiting deploy.

Restarting a service

If your service is misbehaving, you can restart it from your service's Deploys page in the Render Dashboard. Click Manual Deploy > Restart service:

On Render, a service restart is actually a special form of manual deploy:

• Like any other deploy, Render creates a completely new instance of your service and swaps over to it when it's ready.
  • This makes restarting a zero-downtime action.
  • If your service is scaled to multiple instances, a restart applies to all instances.
• Unlike other deploys, the new instance always uses the exact same Git commit and configuration as the running instance at the time of the restart.
  • This means that if you've recently updated your service's environment variables but haven't redeployed since then, restarting does not incorporate those changes.

Rolling back a deploy

See Rollbacks.

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 (Render Postgres or Key Value).
• 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

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

2. 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:

3. 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:

4. After 60 seconds, Render sends a SIGTERM signal to your app's process on the original instance.

   • This signals your app to perform a graceful shutdown.

5. If your app's process doesn't exit within its specified shutdown delay (default 30 seconds), Render sends a SIGKILL signal to force the process to terminate.

   • You can extend your service's shutdown delay. See details.

6. For web services with edge caching enabled, Render purges all of the service's cache entries.

   • This helps ensure that clients receive up-to-date content. See details.

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

Graceful shutdown

As part of deploying your service to a new instance, Render triggers a shutdown of the current instance by sending your application a SIGTERM signal. Your application should define logic to perform a graceful shutdown in response to this signal.

Common shutdown actions include:

• Responding to remaining in-flight HTTP requests
• Completing in-progress worker tasks (or marking them as failed so they're retried by other workers)
• Terminating outbound connections to external services
• Exiting with a zero status after other cleanup actions are complete

If your service is still running after its configured shutdown delay (default 30 seconds), Render sends your application a SIGKILL signal. This terminates the application immediately with a non-zero status.

Setting a shutdown delay

You can't customize the shutdown delay for a service with a persistent disk.

If your service needs more than 30 seconds to complete a graceful shutdown, you can specify a longer shutdown delay (up to a maximum of 300 seconds) in one of the following ways:

• Call the Render API's Update service endpoint and set the maxShutdownDelaySeconds field to the desired value.
• Add the maxShutdownDelaySeconds field to your service's associated render.yaml configuration.
  • Use this method if you manage your service with a Blueprint.

Need more than 300 seconds for graceful shutdown?

Reach out to our support team in the Render Dashboard.