HubGuides / Deploy
Deployment lifecycle
How source becomes a running release, how to verify it, and what happens on failure.
An app is your project. An instance is an environment such as production or staging. Each deployment creates a release for one instance. A service is a component such as a web server, worker, or database.
Follow a deployment
hub deploy waits for the release and prints the result. In Cloud Dashboard, open the app's Releases tab.
| State | Meaning |
|---|---|
| Queued | Hub accepted the deployment. |
| Building | Source is being prepared and built. |
| Starting | Hub is starting or publishing the result. |
| Running | The release completed successfully. |
| Failed | Check the error and build log. |
| Superseded | A newer deployment replaced this attempt. |
When it is running, open the URL and check the app. For background workers, check service status and logs.
For deployments, CLI JSON and MCP return before completion. Poll the returned release when automating. Start, stop, restart, and suspend wait by default, including in JSON and MCP; request an operation ID to run them without waiting.
Recover from a failure
A failed build leaves the previous release serving. Read the failed release's build log, fix the source, and deploy again.
For GitHub deployments, Hub's AI agent can investigate the failure and open a pull request with a suggested fix, when AI assistance is enabled and your organization has allowance remaining. Review and merge the change to deploy it.
Failures during startup can require recovery of the previous release. Apps should tolerate restarts and reconnect to dependencies; deployments are not guaranteed to be interruption-free.
If your connection drops, check Releases before retrying. The deployment may already be running.
Choose the right action
| You want to… | Use |
|---|---|
| Publish changed local files | hub deploy |
| Rebuild the existing source | Redeploy |
| Restart the current processes | Restart |
| Restore an earlier build | Rollback |
| Take the app offline | Stop |
| Pause until the next request | Suspend |
A stopped app stays offline until started or redeployed. Rollback keeps current variables and persistent data; it does not undo migrations.
Releases and rollback · Sleep behavior · Storage and recovery