Configuration Reference

Gimera reads a gimera.yml file from the root of your workspace. It has two top-level sections.

common:
  vars:
    VERSION: 18.0

repos:
  - url: https://github.com/odoo/odoo
    branch: ${VERSION}
    sha: ec8e82986986049f13a3e4414e01337ffaa2675f
    path: odoo
    type: integrated
    patches:
      - patches/odoo

common

Shared settings for every repository in the file.

vars

Key-value pairs referenced elsewhere with ${VAR_NAME}. Their main use is pinning one Odoo version in a single place:

common:
  vars:
    VERSION: 18.0

${VERSION} can then be used in the branch field of every repository, so moving the whole project to a new Odoo release is a one-line change.

repos

A list of repositories to manage. Each entry describes one repository and how gimera should integrate it.

Field	Type	Description
url	string	Git URL to clone. HTTPS (https://) or SSH (git@github.com:)
branch	string	Branch to check out. May reference a variable, e.g. ${VERSION}
sha	string	Commit to pin to. Leave empty to follow the branch head
path	string	Where the repository lands in the workspace. Must be unique per entry
type	string	integrated or submodule — see Gimera
patches	list	Patch files or directories applied after checkout
freeze_sha	bool	Default false. When true, gimera never writes a resolved sha back to this entry
enabled	bool	Default true. false leaves the entry in the file but skips it
merges	list	Extra refs to merge in after checkout, each written <remote> <ref>
remotes	map	Additional named remotes, name: url. Needed for any remote merges refers to
ignored_patchfiles	list	Patch filenames to skip, matched by name
edit_patchfile	string	The patch file gimera edit-patch opens for this entry

freeze_sha

gimera apply -u normally writes the newly resolved commit back into every entry's sha. freeze_sha: true opts one repository out, so it keeps following its branch and your gimera.yml stops recording a moving target for it:

- url: git@github.com:odoo/odoo
  branch: ${VERSION}
  freeze_sha: true
  path: odoo
  type: integrated

To suppress sha write-back for a single run instead of permanently, use gimera apply --no-sha-update, or set GIMERA_NO_SHA_UPDATE=1.

merges and remotes

merges pulls extra refs on top of the checked-out branch — most often an upstream pull request that has not been merged yet, so you can depend on it without forking:

- url: git@github.com:OCA/odoorpc
  branch: master
  sha: c93ebd0221e1bf6a6ca380d614b07c59cf11732e
  freeze_sha: true
  merges:
    - origin refs/pull/69/head
  path: zbsync_odoo/odoorpc_repo
  type: integrated
  patches:
    - zbsync_odoo/odoorpc.patches

Each entry is a remote name and a ref, separated by a space. origin is the repository's own url; anything else has to be declared under remotes:

  remotes:
    upstream: https://github.com/OCA/odoorpc
  merges:
    - upstream refs/heads/fix-branch

A merged pull request ref is a snapshot of someone else's branch, so pin sha and set freeze_sha alongside it — otherwise the content silently changes when that branch is updated.

Patches with chdir

A patches entry is normally a path. It may instead be a mapping, when the patch has to be applied from a different directory than the one it lives in:

patches:
  - path: patches/web
    chdir: addons_OCA/web

Pinning with sha

sha is what makes a build reproducible. branch alone means "whatever that branch points at today", which is fine while developing and dangerous in CI.

Gimera updates the sha values in gimera.yml for you when you run gimera apply -u. Commit the result — that is the record of which commits your project is built from.

To stop gimera writing shas back, use gimera apply --no-sha-update.

Patches

patches lets you carry local modifications to an upstream repository without forking it. Entries are applied after the repository is checked out, and may be:

• a single patch file — patches/odoo/fix.patch
• a directory — patches/odoo/, containing several .patch files

Keeping one patch directory per repository keeps custom changes organised and makes it obvious what has been changed from upstream.

To skip patches for a run, use gimera apply --no-patches (-P), or --do-not-apply-patches.

A full example

common:
  vars:
    VERSION: 18.0

repos:
  - url: https://github.com/odoo/odoo
    branch: ${VERSION}
    sha: ec8e82986986049f13a3e4414e01337ffaa2675f
    path: odoo
    type: integrated
    patches:
      - patches/odoo

  - url: git@github.com:Odoo-Ninjas/zebroo-sync.git
    branch: ${VERSION}
    type: integrated

  - url: https://github.com/OCA/stock-logistics-barcode.git
    branch: ${VERSION}
    sha: f5c7018f13458499c3e84858f9afafee814016b4
    path: addons_OCA/stock-logistics-barcode
    type: integrated
    patches:
      - patches/stock-logistics-barcode

  - url: https://github.com/OCA/web.git
    branch: ${VERSION}
    sha: c17ac76f4a9ba196061afde65af72bba9bc7fa75
    path: addons_OCA/web
    type: integrated

Nested gimera files

A repository brought in by gimera may itself contain a gimera.yml. Running gimera apply -r (recursive) processes those too, the way submodule initialisation recurses.

By default, submodules of an integrated repository are themselves made integrated. gimera apply -s (strict) turns that off and leaves each nested entry as its own gimera.yml defines it.

Best practices

• Use a variable for the Odoo version. One place to change at upgrade time.
• Pin sha, even when you name a branch. The branch documents intent; the sha makes the build reproducible.
• One patch directory per repository. Easier to review than scattered files.
• Keep path values unique. Two entries writing to the same path will collide.
• Prefer integrated for Odoo addons. It produces a single source tree that Odoo can load without submodule bookkeeping.