Performing a rolling release deployment
Use this guide to gradually roll out a new production deployment using rolling releases. You'll configure traffic stages, monitor for errors between stages, and either complete the rolling release or abort if problems arise.
Use this block when you already know what you're doing and want the full command sequence. Use the steps below for context and checks.
# 1. Configure rolling release stages
vercel rolling-release update --cfg '{"enabled":true,"advancementType":"automatic","stages":[{"targetPercentage":10,"duration":5},{"targetPercentage":50,"duration":10},{"targetPercentage":100}]}'
# 2. Deploy to production (starts the rolling release automatically if the project auto-assigns custom domains)
vercel deploy --prod
# 3. Start the rolling release (idempotent if step 2 already started it)
vercel rolling-release start --deployment <deployment-url>
# 4. Monitor the release
vercel rolling-release inspect
vercel logs --environment production --query 'level:error' --since 5m
# 5. Advance to the next stage (if manual approval is configured)
vercel rolling-release approve --deployment <deployment-url> --currentStageIndex 0
# IF errors spike during the release (pass the previous production deployment, not the new one).
# The first command in step 4 lists that deployment as currentDeployment:
vercel rolling-release abort --deployment <previous-production-deployment-url>
# 6. Complete the release (100% traffic)
vercel rolling-release complete --deployment <deployment-url>Set up the traffic stages for your rolling release. Each stage defines what percentage of traffic goes to the new deployment and how long to wait before advancing:
vercel rolling-release update --cfg '{"enabled":true,"advancementType":"automatic","stages":[{"targetPercentage":10,"duration":5},{"targetPercentage":50,"duration":10},{"targetPercentage":100}]}'This configuration sends 10% of traffic to the new deployment for five minutes, then 50% for 10 minutes, then 100%. Adjust the percentages and durations based on your traffic volume and risk tolerance.
To disable rolling releases later:
vercel rolling-release update --no-enableCreate a new production deployment. With rolling releases configured, the deployment won't immediately receive all traffic:
vercel deploy --prodSave the deployment URL from the output for use in the following steps.
Begin the rolling release to start shifting traffic to the new deployment:
vercel rolling-release start --deployment <deployment-url>This starts at the first stage (10% of traffic in the example configuration above). The start command is idempotent. If your project auto-assigns custom domains, the production deployment already started the rolling release, and this command returns its current state. See Starting and completing via the API.
To send 100% of traffic to the canary, run vercel rolling-release complete. See Starting and completing via the API.
Check the current stage, traffic split, and overall progress:
vercel rolling-release inspectWhile the rolling release is in progress, monitor production logs for errors coming from the new deployment:
vercel logs --environment production --query 'level:error' --since 5mTo filter for specific error patterns:
vercel logs --environment production --query 'level:error AND TypeError' --since 5mRun these checks periodically between stage transitions. If your stages have automatic durations, the rolling release advances on its own. If you configured manual approval stages, you'll need to explicitly approve each one.
If your configuration includes stages that require manual approval, advance to the next stage after confirming the current stage is healthy:
vercel rolling-release approve --deployment <deployment-url> --currentStageIndex <stage-index>The --currentStageIndex flag specifies which stage you're approving. Stage indexes start at 0.
After all stages pass, complete the rolling release to send 100% of traffic to the new deployment:
vercel rolling-release complete --deployment <deployment-url>Verify that production is healthy after the full rolling release:
vercel logs --environment production --query 'level:error' --since 5mIf you see a spike in errors during any stage, abort the rolling release immediately. Aborting reverts all traffic back to the previous production deployment, so the abort command takes that deployment, not the new deployment that you saved in step 2. To find it, check the progress of the rolling release again, as in step 4. The output lists the previous production deployment as currentDeployment and the new deployment as canaryDeployment. Copy the url of currentDeployment into the abort command:
vercel rolling-release abort --deployment <previous-production-deployment-url>After aborting, investigate the errors and fix them before attempting another rolling release:
vercel logs --environment production --query 'level:error' --since 30mWas this helpful?