Configuration

odx reads the [tool.odx] table of the project’s pyproject.toml. Only odoo_version is required; every other key has a default. Unknown keys are errors, so a typo never goes unnoticed; Stability says what a release may change.

Durations are written as a number and a unit: "90s", "15m", "12h", "7d". Paths are relative to the project root.

The settings of the person rather than the project (forge tokens, mirrors, local clones, the cache location) live in the user configuration.

[tool.odx]

Key	Type	Description
odoo_version	string	Odoo series of the project, e.g. "17.0".
languages	list of strings	Languages the project is translated into besides English, as Odoo codes ("es", "nl_BE"). Default: none (English only).
project_id	string	Neutral project identifier for the verdict repository. Default: the first twelve hex digits of the SHA-256 of the project’s origin URL.
jobs	integer	Maximum concurrent fetches and merge jobs. Default: the number of CPUs.
cache_dir	path	Cache directory, relative to the project root. Default: the shared cache directory of the user configuration, else .odx/cache.
merge_strategy	"rebase" | "merge"	How merges are applied on top of the base. Default: "rebase".
mergiraf	"auto" | "always" | "never"	When to use mergiraf for conflict resolution. Default: "auto".
on_conflict	"abort" | "skip"	Default conflict policy for merges. Default: "abort".
on_head_change	"pin" | "follow-if-green" | "follow"	Default force-push guard-rail policy. Default: "follow-if-green".
lockfile	path	Lockfile path, relative to the project root. Default: odx.lock.

[tool.odx.mirror]

The private vault repository.

Key	Type	Description
url	string	Push URL of the vault repository; must be private.
ref_prefix	string	Prefix of content-addressed refs. Default: refs/odx.
ref_style	"refs" | "tags"	Whether locked commits are kept under refs or tags. Default: "refs", or "tags" when the vault protects tags (GitLab, or created with auto_create).
push_on_lock	boolean	Push locked commits on odx lock. Default: on.
auto_create	boolean	Create the vault repository through the forge API. Default: off.
allow_public	boolean	Allow a public vault repository. Default: off.

[tool.odx.http]

How odx talks to forges over HTTP.

Key	Type	Description
per_host_concurrency	integer	In-flight requests and fetches per host. Default: 6.

[tool.odx.cache]

Cache staleness and prefetching.

Key	Type	Description
prefetch_wheels	boolean	Let odx sync prefetch wheels. Default: on.

[tool.odx.cache.ttl]

How long cached data is used before it is refreshed.

Key	Type	Description
refs	duration	How long fetched git refs are used before fetching again. Default: "15m".
pr_state	duration	How long a kept dashboard (pull request states) is shown before it is rebuilt. Default: "30m".

[tool.odx.dashboard]

What odx dashboard shows.

Key	Type	Description
sections	list of "pinned" | "droppable" | "new-upstream" | "forward-port" | "backport" | "auto-update" | "glue" | "wanted" | "drift" | "suppressed"	The sections odx dashboard shows when --section is not given. Default: all.
environment_pairs	list of pair of strings	Environment pairs compared in the drift section. Default: every promotion edge between environments that are not disposable.

[tool.odx.groups]

Dependency group name → vendor directory.

Key	Type	Description
default	string	Group used by add and check-deps --fix, and by packages that name none. Default: none.
project_addons	list of paths	Committed project addon directories. Default: [tool.odx.layout] project_addons, else the project root.
<name>	table of paths	Group name → directory.

[[tool.odx.repositories]]

A repository aggregated from its base and merges.

Key	Type	Description
name	string	Short name, unique in the project. Default: url.
url	string	Upstream URL.
target_dir	path	Working tree directory. Default: <aggregate_dir>/<last segment of name>.
base	string	Base branch. Default: odoo_version.
target_branch	string	Aggregated branch, as exported to repos.yaml. Default: <base>-odx.
forge	"github" | "gitlab" | "gitea"	Forge kind when it cannot be derived from the URL. Default: derived from the URL.
addons	list of strings	Addon globs to link (the doodba addons.yaml selection). Default: every addon.

[[tool.odx.repositories.merges]]

One merge source: exactly one of pr, sha or branch.

Key	Type	Description
pr	integer	Pull request number.
sha	string	Commit SHA.
branch	string	Branch name.
remote	string	Remote URL of branch. Default: the repository URL.
on_conflict	"abort" | "skip"	Conflict policy for this merge. Default: [tool.odx] on_conflict.
on_head_change	"pin" | "follow-if-green" | "follow"	Guard-rail policy for this merge. Default: [tool.odx] on_head_change.
track_upstream	boolean	Report when the pull request is merged upstream. Default: on.

[tool.odx.packages.<name>]

A package pinned to a git source.

Key	Type	Description
repo	string	Repository as owner/repo on GitHub.
url	string	Repository URL. Default: https://github.com/<repo>.git.
pr	integer	Pull request number.
branch	string	Branch.
tag	string	Tag.
rev	string	Commit.
subdirectory	string	Subdirectory of the addon in the repository. Default: the repository root.
group	string	Dependency group. Default: [tool.odx.groups] default.

[tool.odx.vendor]

How addons are vendored into the project.

Key	Type	Description
bump_on_content_change	boolean	Bump the last manifest version segment on content changes. Default: on.
exclude	list of strings	Files removed from vendored addons. Default: ["static/description/index.html"].
manifest	path	Vendor manifest path. Default: [tool.odx.layout] vendor_manifest, else .odx/vendor.lock.

[tool.odx.lock]

Lockfile options.

[tool.odx.lock.auto_update]

Automatic re-lock of index packages.

Key	Type	Description
policy	"last-segment" | "none"	Which version changes are applied automatically. Default: "last-segment".
allow	list of strings	Distribution globs allowed. Default: ["odoo-addon-*"].
deny	list of strings	Distribution globs denied. Default: none.
content_check	boolean	Compare wheel contents before applying. Default: on.
allowed_paths	list of strings	Paths allowed to change when content_check is on. Default: i18n/*.po, i18n/*.pot, README.rst, readme/** and static/description/**.

[tool.odx.upgrade]

Upgrade analysis (odx migrate plan).

Key	Type	Description
target_odoo_version	string	Target Odoo series. Default: none (pass --target).

[tool.odx.index]

The addon index that maps addons to repositories.

Key	Type	Description
ttl	duration	How long the cached addon index is used. Default: "7d".
orgs	list of strings	Organizations whose forge listings are indexed, as names on GitHub or URLs. Default: none.
sources	list of "overrides" | "cache" | "package-index" | "forge" | "oca-repo-list" | "openupgrade"	Sources, in trust order. Default: all.
overrides	table of table of strings	Addon → series → owner/repo. Default: none.
renames	table of table of strings	Series → old name → new name. Default: none.

[tool.odx.port]

Porting commits between series.

Key	Type	Description
default_from	list of strings	Default source series. Default: the series just below and just above the target.
repo_wide_threshold	integer	Commits touching more addons are repo-wide. Default: 5.
migration_commit_patterns	list of strings	Commit subjects that are never proposed, as case-insensitive regular expressions. Default: ^\[MIG\] and ^\[ADD\].*\bmigration\b.
squash_authors	list of strings	Author e-mails of bots whose commits odx migrate squashes. Default: the OCA bots.
squash_subjects	list of strings	Text in a subject that marks a bot commit to squash. Default: the OCA bots’ commits.

[tool.odx.suggest]

Upstream suggestions.

Key	Type	Description
series	list of strings	The series odx suggest looks on when --from is not given. Default: [tool.odx.port] default_from, else the series just below and just above.

[tool.odx.features.<name>]

A named set of addons promoted together.

Key	Type	Description
modules	list of strings	Addons that make up the feature.
description	string	Functional description. Default: none.

[tool.odx.layout]

Where the project keeps its files.

Key	Type	Description
project_addons	list of paths	Committed project addon directories. Default: the project root.
aggregate_dir	path	Parent of repository working trees. Default: vendor.
groups	table of paths	Alias of [tool.odx.groups] directories. Default: none.
requirements	path	Platform requirements file. Default: requirements.txt for the odoo-sh profile, else dist/requirements.txt.
vendor_manifest	path	Vendor manifest. Default: .odx/vendor.lock.

[tool.odx.platform]

The deployment platform.

Key	Type	Description
profile	"generic-wheels" | "vendored-source" | "odoo-sh" | "custom"	Platform profile. Default: "generic-wheels".
provided	string	Provided-package set name or constraints file. Default: odoo-sh for the odoo-sh profile, else odoo-standard.
provided_extra	list of strings	Extra provided requirements. Default: none.
provided_remove	list of strings	Packages removed from the provided set. Default: none.
index	string	Package index name for publishing. Default: private.

[tool.odx.platform.custom]

Hooks of the custom platform profile.

Key	Type	Description
prepare	string	Command that prepares the deployment. Default: none.
verify	string	Command that verifies the deployment. Default: none.

[tool.odx.environments]

Environments and how changes are promoted between them.

Key	Type	Description
preset	"major-branches" | "series-branches" | "main-production" | "odoo-sh" | "explicit"	Layout preset. Default: "explicit" when environments are declared under env, else "major-branches".
series	string	Default series of the environments. Default: odoo_version.
branch_specific	list of strings	Files that differ per environment. Default: none.
promotion	list of pair of strings	Allowed promotion edges. Default: the preset’s.

[tool.odx.environments.env.<name>]

One environment.

Key	Type	Description
branch	string	Branch name or pattern with {series} and {major}. Default: the preset’s, else the environment name.
role	"dev" | "test" | "uat" | "prod"	Environment role. Default: the preset’s, else implied by a name dev, test, uat or prod.
series	string	Series of this environment. Default: [tool.odx.environments] series.
repo	string	Separate repository of this environment. Default: none (the project repository).
disposable	boolean	Excluded as a promotion target unless named explicitly. Default: on for the uat role, else off.
url	string	URL of the environment’s Odoo instance. Default: none.
database	string	Database of the environment. Default: none.
connection	string	Connection file of the environment, relative to the project, for tools that read and write its database (a Fluvo connection.conf); it holds the credentials, so keep it out of git. Default: none.

[tool.odx.promote]

Defaults of odx promote.

Key	Type	Description
allow_downgrade	boolean	Allow copying an older pin over a newer one. Default: off.
with_code	boolean	Cherry-pick project addon commits unless --no-with-code. Default: off.
with_odoo	boolean	Promote the Odoo core revision together with the pins. Default: on.
search_synonyms	table of list of strings	Extra synonyms for --search. Default: none.

[tool.odx.bot]

The automation bot (odx bot).

Key	Type	Description
environment	string	Environment that receives bot pull requests. Default: the branch checked out.
dashboard	boolean	Maintain the dashboard issue. Default: on.
max_prs_per_run	integer	Maximum pull requests per run. Default: 10.
labels	list of strings	Extra labels on every bot pull request, besides odx’s own. Default: none.
mute_expiry	duration	Expiry of mutes made from the dashboard. Default: "180d".
auto	list of "drop-override" | "repin" | "auto-update"	Kinds opened without a checkbox. Default: all.
promote_label	string	Label that triggers a promotion pull request. Default: promote.
vault_heads	boolean	Vault every observed tracked head. Default: off.
allow_public	boolean	Run on a public project repository. Default: off.
notify	list of strings	Forge users mentioned when a wanted addon’s migration starts or lands. Default: none.

[tool.odx.dev]

Local development (odx dev).

Key	Type	Description
venv	path	Virtual environment directory. Default: .venv.
addons_path_file	path	File listing the addons path. Default: .odx/addons-path.
odoo_conf	path	Odoo configuration file whose addons_path is updated. Default: none.
editable	boolean	Use editable installs. Default: on.
dev_dir	path	Directory for develop-mode clones. Default: .src.

[tool.odx.lint]

Defaults of odx lint.

Key	Type	Description
paths	list of paths	Paths linted by default. Default: the project addon directories.
only_changed	boolean	Only lint changed addons. Default: off.

[tool.odx.sniff]

The migration script sniffer.

Key	Type	Description
fail_on_new	boolean	Fail when merges introduce migration scripts. Default: off.

[tool.odx.check_deps]

Defaults of odx check-deps.

Key	Type	Description
provided	list of strings	Addons the platform provides beyond Odoo’s community addons (for example enterprise addons), counted as available. Default: none.

[tool.odx.glue]

Glue addons (odx glue).

Key	Type	Description
ignore	table of strings	Glue addons the project does not want, each with why. Default: none.

[[tool.odx.wanted]]

An addon the project may need later. odx wanted says per series whether it is there, whether someone is migrating it, or neither.

Key	Type	Description
addon	string	The addon’s technical name.
series	list of strings	Series to watch it on. Default: odoo_version.
repository	string	Its repository, as owner/repo on GitHub or a URL. Default: where the addon index finds it.
note	string	Why it is wanted. Default: none.