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

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.