Introduction
An Odoo.sh deployment involves more than moving code into production. A customization that works in development can fail against real business data, existing integrations, different user permissions, or production configuration.
Odoo.sh gives you development, staging, and production stages, plus a Git branch workflow that lets you validate changes before they touch live operations. This guide explains how each stage behaves, how to test and approve a release, and how to handle failures and rollbacks.
How Odoo.sh Stages Work
Each branch on Odoo.sh sits in one of three stages, and each stage builds differently. Understanding the differences prevents most deployment surprises.
Stage | What a Build Does | Database | Backups |
Development | Creates a new database, loads demo data, and runs the unit tests | A new database for each build | Cannot be backed up |
Staging | Duplicates the production database and loads the copy with the staging revision | A fresh copy of production on every push | Manual backups possible |
Production | Loads the current production database with the new revision | Your live database | Automatic backups |
Three details matter most:
A failed production build does not take production down: If a build fails to load or update the production database, Odoo.sh keeps running the previous successful build.
Staging resets on every push: Each push to a staging branch builds from a fresh copy of production, so configuration changes you make in staging do not carry into the next build or into production.
Staging cannot be promoted to production: You can move a development branch to staging, but you cannot move a staging branch to production. Merge your development branch into the production branch through Git.
Builds finish with one of three statuses: successful (no errors or warnings), almost successful (warnings, no errors), or failed (errors). Treat warnings as work to review, not as a pass.
Prepare the Repository Before Development Begins
A reliable deployment process starts with a clear repository and module structure. A reliable deployment process starts with a clear repository and module structure. If you are new to how Odoo modules are organized, see our guide on how to build a custom module in Odoo. Before development begins:
Confirm the target Odoo version.
Review module dependencies and third-party components.
Keep custom code in version control.
List extra Python packages in a requirements.txt file at the root of the branch, so Odoo.sh installs them in your containers.
Add private submodules with a deploy key, so Odoo.sh can download them.
Agree on branch naming and code-review practices.
Document configuration requirements.
Identify the integrations and workflows the change affects.
Give each change a clear purpose and a defined way to test it. Avoid combining unrelated fixes into one release when that makes failures harder to diagnose. For example, a change to an inventory validation rule should include the code, the intended behavior, and test cases for valid and invalid stock operations. For custom features that require new code or changes to existing modules, explore our Odoo development services. We build, test, and maintain changes within your Odoo environment.
Build and Test Changes in Development Branches
Development branches give you a place to work on changes before staging. A practical workflow is:
Create a branch for the feature or fix.
Make the code change and commit it.
Review the build result and the application logs.
Test the affected functionality.
Correct failures before you ask for broader testing.
A development build creates a new database, loads demo data, and runs the unit tests. A build fails if tests fail during installation. Depending on the modules you install and test, a development build can take up to an hour, so choose the modules to install deliberately.
A successful build is useful evidence, but it does not prove that every business workflow works. Verify that dependencies are available, module updates complete, and the feature behaves as intended. Use automated tests to catch regressions early, and test manually where workflows involve user interaction, permissions, and external systems. When a deployment involves changes to standard Odoo features, workflows, or existing modules, our Odoo customization services can adapt the system to your business requirements.
Validate Changes in an Odoo.sh Staging Environment
Staging is where a team checks whether a change is ready for production. Staging builds use a neutralized copy of the production database. Certain behaviors, such as scheduled actions and outgoing emails, are altered to reduce unintended effects, and the mail catcher intercepts outgoing email. Account for those differences, and do not assume staging behaves exactly like production.
Test the workflows the change affects, including:
Creating, updating, and validating business records
User roles and access permissions
Reports, calculations, and automated actions
Integration behavior and error handling
Existing functionality the update could affect
Performance with representative data volumes
For example, test a sales workflow change from quotation creation through order confirmation and the downstream steps your business uses. Use test records carefully, and confirm that emails, payment providers, shipping connectors, and other external actions do not trigger against live systems. If an integration fails in staging, our guide to common Odoo integration errors and how to fix them covers the usual causes.
Because every push builds from a fresh copy of production, you can test against current data. When you want to start over with a new copy, request a rebuild. Record the results, and document any issue that stays unresolved
Set Production Release Approval Criteria
Do not deploy because the code compiles or the build is green. Before you approve a release, confirm that:
The change has been reviewed.
The relevant tests have passed.
Business owners have accepted the affected workflow.
You have assessed the data and module updates.
You understand the backup and recovery arrangements, and you have created a manual backup before a risky release.
Known limitations are documented.
The person responsible for approving the release has signed off.
For higher risk changes, define a release window and name the person who monitors the application after deployment. A label change needs little testing. A change to inventory valuation, accounting logic, access controls, or critical integration needs a thorough review.
Deploy Changes and Verify the Live Environment
Once a release is approved, merge the change into the production branch. Pushing production creates a build that tries to load the live database with the new revision. Do not treat deployment as complete when the code reaches production. Run a focused post-deployment check:
Confirm that the production build completes successfully.
Check the logs for errors.
Open the affected business workflow.
Create or update a representative record.
Verify calculations, reports, permissions, and integration behavior.
Confirm that the business process continues normally.
Match the checks to the risk. A change that affects invoice generation should include invoice validation, and a change to inventory reservations should include a stock workflow. Record the result and tell the people the release affects.
Deployment checks should be part of a wider maintenance routine. Use our Odoo maintenance checklist to review other areas that need regular attention after changes go live.
Handle Failed Builds and Deployment Regressions
A failed build and a production regression are different problems, and they call for different responses.
A failed build comes from missing dependencies, syntax errors, failing tests, or incompatible code. Review the build logs, find the first meaningful failure, and fix the underlying cause before you retry. On production, a failed build leaves the previous revision running, so users do not see the failure.
A production regression happens when a release that built successfully breaks existing functionality. Respond in this order:
Establish the scope and business impact.
Pause further risky changes.
Review the release history and logs.
Choose a safe correction or recovery path.
Test the fix before you deploy it.
Verify the affected workflow after recovery.
Two recovery paths exist, and they differ. Reverting the commit in Git and pushing creates a new build with the previous code, which fixes code problems. Restoring a database backup recovers data problems, but it overwrites transactions entered after the backup. Reverting code does not reverse database changes or external actions that already occurred. For major incidents, involve the people responsible for the Odoo.sh environment and the affected business processes instead of improvising a recovery.
Keep Development, Staging, and Production Consistent
Differences between environments make a tested change behave differently after release. The usual causes are:
Different installed modules or module versions
Missing environment-specific settings
Different access rights or user groups
Test credentials versus production credentials
External services configured differently
Data volumes that differ significantly
Manual changes made directly in one environment
Data volume differences often show up as performance problems after release, when a workflow that ran quickly in testing slows down on the full production database. Our guide on how to optimize a slow Odoo database explains how to find and fix those bottlenecks. Document required settings and dependencies. Keep credentials out of source code, and use proper secret management. Review access to each environment too. Odoo.sh collaborators have different roles: Admins have full access to Odoo.sh features and tools, while Testers can work with staging and development databases but cannot access the production database through Odoo.sh tools. Give people the access they need and no more production access than that.
Keeping environments consistent requires ongoing attention to configuration, access, and system changes. Explore Odoo managed services for support with ongoing maintenance, troubleshooting, and system management.
Odoo.sh Tools to Use During a Release
Logs: check build, update, and server logs for errors and warnings.
Web Shell: run commands and inspect the database from the browser.
Editor: make quick changes in development and staging builds.
Monitoring: watch the live environment after a release.
Outgoing emails: review the emails a staging or development build intercepted.
Backups tab and DB dump: download or restore backups, and create a manual backup before risky changes.
Common Odoo.sh Deployment Mistakes
Treating a green build as business sign-off
Testing only with demo data, and never with a production copy
Assuming configuration changes made in staging carry over to production
Deploying on a busy day with no release window or named owner
Editing production directly instead of going through a branch
Skipping a manual backup before a risky change
Ignoring warnings on an almost successful build
Hardcoding credentials in the repository
Odoo.sh Deployment Checklist
Use this checklist before each production release:
The change is committed and reviewed.
Dependencies and version compatibility are confirmed.
The development build completes successfully.
Relevant automated and manual tests pass.
Staging tests cover the affected business workflows.
Access permissions and integrations are verified.
Database and module-update requirements are understood.
A manual backup exists, and recovery options and release ownership are clear.
Post-deployment checks are prepared.
The result is documented and communicated.
Conclusion: Make Odoo.sh Releases More Predictable
A repeatable deployment workflow reduces uncertainty by making testing, approval, and recovery responsibilities clear. Development builds, staging validation, controlled production releases, and post-deployment checks each serve a distinct purpose. Apply them consistently, and you reduce avoidable regressions and make every Odoo change easier to review, release, and maintain. If your team needs help developing custom modules, preparing releases, or troubleshooting deployment issues, Reach out to our Odoo Development Team to discuss the support your environment requires.
