Deploying Changes

To deploy changes to your code you will first create a Release and then promote it.

Promoting a Release will begin a rolling deployment that will continue until the new Release is active on all Processes or has been completely rolled back.

One Step

To create a Release and promote it in one step, use convox deploy:

    $ convox deploy -a myapp
    Packaging source... OK
    Uploading source... OK
    Starting build... OK
    ...
    Build: BABCDEFGHI
    Release: RBCDEFGHIJ
    Promoting RBCDEFGHIJ...
    2026-03-18T14:30:49Z system/k8s/atom/app Status: Running => Pending
    2026-03-18T14:30:51Z system/k8s/web Scaled up replica set web-745f845dc to 1
    2026-03-18T14:30:51Z system/k8s/web-745f845dc Created pod: web-745f845dc-rzl2q
    2026-03-18T14:30:51Z system/k8s/web-745f845dc-rzl2q Successfully assigned convox-myapp/web-745f845dc-rzl2q to instance-0a1b2c3d4e5f
    2026-03-18T14:30:51Z system/k8s/web-745f845dc-rzl2q Pulling image "registry.host/convox/myapp:web.BABCDEFGHI"
    2026-03-18T14:30:53Z system/k8s/atom/app Status: Pending => Updating
    2026-03-18T14:30:55Z system/k8s/web-745f845dc-rzl2q Successfully pulled image "registry.host/convox/myapp:web.BABCDEFGHI"
    2026-03-18T14:30:56Z system/k8s/web-745f845dc-rzl2q Created container main
    2026-03-18T14:30:56Z system/k8s/web-745f845dc-rzl2q Started container main
    OK

Two Steps

You can also perform the steps of creating the Release and promoting it with two different commands. This is useful if you would like to make changes to Environment Variables or run migrations against the new Release before it is pushed live.

    $ convox build -a myapp
    Packaging source... OK
    Uploading source... OK
    Starting build... OK
    ...
    Build: BABCDEFGHI
    Release: RBCDEFGHIJ

    $ convox releases promote RCDEFGHIJK -a myapp
    Promoting RCDEFGHIJK...
    2026-03-18T14:30:49Z system/k8s/atom/app Status: Running => Pending
    2026-03-18T14:30:51Z system/k8s/web Scaled up replica set web-745f845dc to 1
    2026-03-18T14:30:51Z system/k8s/web-745f845dc Created pod: web-745f845dc-rzl2q
    2026-03-18T14:30:51Z system/k8s/web-745f845dc-rzl2q Successfully assigned convox-myapp/web-745f845dc-rzl2q to instance-0a1b2c3d4e5f
    2026-03-18T14:30:51Z system/k8s/web-745f845dc-rzl2q Pulling image "registry.host/convox/myapp:web.BABCDEFGHI"
    2026-03-18T14:30:53Z system/k8s/atom/app Status: Pending => Updating
    2026-03-18T14:30:55Z system/k8s/web-745f845dc-rzl2q Successfully pulled image "registry.host/convox/myapp:web.BABCDEFGHI"
    2026-03-18T14:30:56Z system/k8s/web-745f845dc-rzl2q Created container main
    2026-03-18T14:30:56Z system/k8s/web-745f845dc-rzl2q Started container main
    OK

Troubleshooting Failed Deployments

If a deployment fails or hangs, use convox deploy-debug to diagnose the issue:

    $ convox deploy-debug -a myapp

This command inspects your app's pods and provides actionable hints for common failure states like crash loops, image pull errors, OOM kills, and health check failures. See the deploy-debug reference for details.

See Also

• Rolling Updates for how Convox handles zero-downtime deployments
• Rollbacks for reverting to a previous release
• CI/CD Workflows for automating deployments