Repository & Branch Flow
This page documents how Git branches are configured at different levels and how they flow through to actual deployment on your servers — using real Odoo ecosystem branch naming conventions.
Odoo Branch Naming Convention
Odoo uses a specific branch naming scheme that the platform fully supports:
| Branch Type | Format | Example | Purpose |
|---|---|---|---|
| Stable / Production | <version> | 18.0, 17.0 | Stable release branches — used for production deployments |
| Development | <version>-<feature>-<trigram> | 18.0-sale-fixes-pgs | Feature or bugfix work targeting a specific Odoo version |
| Next version | master | master | Upcoming unreleased Odoo version |
Branch name components:
<version>— The target Odoo version:17.0,18.0,19.0, ormaster<feature>— Hyphen-separated description:sale-fixes,fix-invoices,stock-valuation<trigram>— Three-letter author identifier (usually initials):pgs,jco,aks
Version branches like 18.0 and 19.0 are considered stable/production branches. Development work happens on <version>-<feature>-<trigram> branches and gets merged back to the version branch.
Branch Resolution Hierarchy
When a deployment is triggered, the platform resolves which Git branch to use with a simple fallback chain:
Priority order:
- Environment branch (highest) — set per-environment, e.g.
18.0-fix-invoices-pgsfor a dev environment - Project branch — the stable version branch, e.g.
18.0 - "main" (lowest) — hardcoded fallback if nothing is configured
Changing a branch setting does not auto-redeploy. You must trigger a new deployment to pick up branch changes.
Environment Creation
When you create a new environment, the branch is set automatically based on what you provide:
If you don't specify a branch, the environment inherits the project's default branch (typically the stable version branch like 18.0).
Addon Repository Resolution
The platform collects repositories from multiple sources, each with their own branch logic:
Repository Tiers
| Tier | Source | Branch Logic | Example |
|---|---|---|---|
| Platform | OCA repos, curated addons | Matched by Odoo version | OCA/web -- branch 18.0 |
| Organization | Org-level shared repos | Uses the repo's configured branch | org/shared-modules -- branch 18.0 |
| Project Primary | Project's main repository | Uses the project's default branch | myorg/odoo-custom -- branch 18.0 |
| Project Additional | Extra repos added per project | Uses the repo's configured branch | myorg/connector-ecommerce -- branch 18.0 |
| Environment Override | Per-environment overrides | Can override any tier's branch | Dev env: 18.0-sale-fixes-pgs instead of 18.0 |
The project primary repo can never be excluded via environment overrides — it is always included in deployments.
Real-World Scenarios
Scenario 1: Standard Production Deployment
An agency running Odoo 18.0 for a client — all environments on the stable branch:
All environments use the stable 18.0 branch. Simple and consistent.
Scenario 2: Development Workflow with Feature Branches
A developer working on sale order improvements while production stays stable:
The dev environment deploys from a feature branch (18.0-sale-fixes-pgs) while prod and staging remain on stable 18.0.
Scenario 3: Hotfix on Production
A critical invoice bug needs immediate patching on production:
After merging the hotfix into the stable 18.0 branch, clear the production environment's branch override so it returns to 18.0 on the next deploy.
Scenario 4: Multi-Version Agency
An agency managing clients on different Odoo versions:
Each project targets a different Odoo version. Platform addon repos (OCA, etc.) automatically resolve the correct branch per version (17.0, 18.0, 19.0).
Scenario 5: Addon Branch Override per Environment
Testing a new connector version on staging while production stays on stable:
The staging environment uses a per-environment branch override to deploy connector-shopify from branch 18.0-shopify-v2-aks while everything else stays on 18.0.
Branch Configuration Summary
| Scenario | Project Branch | Environment Override | Deployed Branch |
|---|---|---|---|
| Stable production | 18.0 | (none) | 18.0 |
| Feature development | 18.0 | 18.0-sale-fixes-pgs on dev | 18.0-sale-fixes-pgs |
| Production hotfix | 18.0 | 18.0-fix-invoices-jco on prod | 18.0-fix-invoices-jco |
| Staging QA | 18.0 | 18.0-stock-valuation-aks on staging | 18.0-stock-valuation-aks |
| Next version testing | 18.0 | master on test env | master |
| Addon override | 18.0 | Override on specific addon repo | Addon: 18.0-shopify-v2-aks, Primary: 18.0 |
| Legacy client | 17.0 | (none) | 17.0 |
| Cutting-edge client | 19.0 | (none) | 19.0 |
Use stable version branches (17.0, 18.0, 19.0) as your project default. Only use development branches (18.0-feature-xxx) as environment-level overrides for dev/staging environments.