2. Bureaucrat Knowledge
  3. Yodoo Documentation
  4. Admin Guides
  5. Addons Management
 

Assembly workflow

In this articalt we will basically describe following topics:

- What is assembly

- What is the usage of assembly?

- How to use assemblies (basic assembly workflow)

What is assembly

Assembly is separate git repository that is automatically or semiautomatically populated (and updated) with odoo addons, described in assembly configuration file (odoo-packager.yml).

Usually, each assembly repository contains assembly configuration file named odoo-packager.yml in the root of repository.

This file is used to tell the system, what addons (paramater addons-list) have to be present in this repository and where system have to look for addons (parameter git-soures).

Usually assemblies are created, configured and managed via Yodoo Cockpit user interface. But also manual management of assembies via gitlab user interface is availabe.

Why assemblies

The main reason on using assemblies - is because assembly allows you to have full control on update process. You always know when and what addons were updated on the server. You can easily check what was changed. And if there are some bug introduced, you can easily roll back to previous commit (because it is git).

One more cool feature of assembly, that in 95% your will always update all addons at once, this way 95% that all your addons will be compatible. But also, if needed, it is possible to configure assembly to update only specific addons.

Usage of asemblies

There are few common types of assembly usage:

1. When assembly created to provide client some set of addons, to ensure that all of them updated at same moment and all of them are compatible with each other.

2. When assembly is used to manage third-party addons available on the server.

These two types of assemblies has similar workflow, but the assembly that is used to manage server addons has one more step - update of addons on the server.

There are following common operations available on assemblies:

1. Add new module (from git-rpository, from odoo_apps)

2. Remove existing module

3. Update all modules in assemblies

Syntax of odoo-packager.yml

Most recent documentation on packager is available at its repository: https://gitlab.crnd.pro/crnd/docker/odoo-apps-packager

Here, only basic syntax will be described.

So, the odoo-packager.yml file is YAML file, that is used to describe what addons have to be placed in the repository. Be aware of spaces when you edit this file.

The odoo-packager.yml looks like the example below:

addons-list:
    # Usualy contains only list of addon names
    - generic_condition
    - generic_rule
    - website_snippet_anchor
    - auth_saml

    # Download addon from odoo apps
    - name: bureaucrat_helpdesk_lite
      odoo_apps: true

# List of git repositories to fetch addons from.
# First git source where addon was found used as source for addon.
git-sources:
    # Usually it is enough to specify repository url only
    - url: "https://github.com/OCA/website"

    # This is shortcut for OCA repositories located under github.com/OCA
    # and internaly it will be converted to
    # url: "https://github.com/OCA/server-auth"
    - oca: server-auth

    # There is one more shortcut available: 'github'.
    # specification below will be automatically converted to
    # url: "https://github.com/OCA/web"
    - github: OCA/web

    # There is also shortcut for repositories located on gitlab.crnd.pro available:
    - crnd: crnd-opensource/generic-addons

Basically, odoo-packager.yml consists of two sections: addons-list and git-sources.

In first one (addons-list) we have to specify list of addons, and in second one (git-sources) we have to specify list of repositories to look for addons in.

Requirements for connected git sources

Mainly there is only one requirement for connected git sources - it have to follow correct naming of branches.

Usually odoo-packager expected following branch naming convention in connected repos:

  • All stable branches have to be named same as odoo serie. For example: 13.0, 14.0, etc.

  • Stable branch must contain only addons for corresponding odoo version. Do not mix addons for v13.0 and v14.0 in single git branch

  • Single repository may contain multiple stable branches for different Odoo versions.

Take a look at OCA repositories, and Odoo repostiory to see correct branch naming.

Basic assembly workflow

The content of assembly is managed via gitlab and Continious Integration (CI) jobs.

The main rules for workflow on assembly are following:

1. The stable branch (that contains actual code) is always named as Odoo serie. For example: 12.0, 13.0, 14.0, etc.

2. Each update have to be started on branch named <odoo serie>-update. For example: 12.0-update.

3. This way, all changes have to be passed through Merge Requests, this way it will be much easier to track history in future.

4. When all changes merged, then the update branch (12.0-update) have to be removed.

5. Only one update in same time allowed. Usually it is enough for assembly to have only one update branch.

6. Optionaly, in case of assemblies binded to Odoo server, the additional CI job have to be triggered manually (when update complete, and changes are settled on stable branch). This job is named update-addons, and will be created automatically (but no started automatically) on each push (merge) to stable branch.

7. Everything in dist folder will be overwritten by pacager on next update

8. If you need to add custom modules, that could not be fetched automatically, then you have to place them in: a) separate git repository and configure assembly to search for them there, b) place then in custom_addons folder in assembly.

This way, adding new odoo module to assembly consists of following steps:

1. Create new branch 12.0-update and create Merge Request to merge this new branch to stable one (12.0)

2. Switch to that branch and open odoo-packager.yml in editor (possibly Web IDE on gitlab).

3. Add required changes to odoo-packager.yml.

4. Manually trigger new pipeline on 12.0-update branch. See GitLab documentation for this step here.

5. After pipline started, wait while it completes and if everything is ok (it is green) go to next steps. If pipeline failed, then check pipeline job's log, find the reason and return to 3, possibly you forgot about dependencies.

6. Check the Merge Reqeuest created in 1, and review changes. There have to be added / updated addons present.

7. If everything ok (as expected), then merge this Merge Request

8. Optionally, if this assembly is binded to server, go to pipelines check if there are automatically created pipeline for stable branch with job named update-addons. If such job not available, trigger new pipeline for this stable branch (12.0) manually. After this job completed, all new addons will be available on server.

Adding new module

It is a common task, to add new module to assembly.

But there are following types of this common operation:

1. Adding module from OCA (Odoo Community Association) repositories (https://github.com/OCA).

2. Adding module from any GitHub repository

3. Adding module from any CR&D repository

4. Adding module from any public git repository

5. Adding module from Odoo Apps (only free modules could be added / updated automatically)

6. Adding other modules, that could not be updated automatically.

7. Adding module from private git repository


1. Adding new OCA module

This could be easily done via following steps:

1.1. Add name of addon to addons-list section of odoo-packager.yml
1.2. Add correct repository to git-sources section of odoo-packager.yml using shortcut oca: repo-name

For example, odoo-packager.yml that adds OCA module 

addons-list:
    - partner_contact_birthdate
git-sources:
    - oca: partner-contact
2. Adding module from github repo

This could be easily done in similar way to adding OCA repo.

2.1. Add name of addon to addons-list section of odoo-packager.yml
2.2. Add correct repository to git-sources section of odoo-packager.yml using shortcut oca: repo-name

For example, odoo-packager.yml that adds OCA module using github shortcut:

addons-list:
    - partner_contact_birthdate
git-sources:
    - github: OCA/partner-contact
3. Adding module from CR&D gitlab repo

We have shorcut to easily add modules from CR&D repos to assemblies.

The benefits of this shortcut, it will automatically resolve access rights, using access rights of user that executes the CI job, that packages modules to repo.

Following codesample will add module crnd_web_button_box_full_width from repo https://gitlab.crnd.pro/crnd-opensource/crnd-web to assembly.

addons-list:
    - crnd_web_button_box_full_width
git-sources:
    - crnd: crnd-opensource/crnd-web
4. Adding module from any public git repo

In this example, we will add module generic_tag from https://github.com/crnd-inc/generic-addons repository, using standard syntax (without shortcuts).

See example below:

addons-list:
    - generic-tag
git-sources:
    - url: https://github.com/crnd-inc/generic-addons
5. Adding module from Odoo Apps store

Adding free apps to assembly from Odoo Apps store, is one of the easiest tasks.
All you need is to specify app name in the list of addons, and mark it as downloadable from Odoo Apps.

Take a look at following snippet:

addons-list:
    - partner_contact_birthdate
    - name: bureaucrat_helpdesk_lite
      odoo_apps: true
git-sources:
    - oca: partner-contact

In this example, we try to add bureaucrat_helpdesk_lite to assembly.

Pay attention at the syntax. In this example in addons list we use two types of objects:
- string, as usual only addon name for standard OCA module
- mapping, that provides more info on bureaucrat_helpdesk_lite addon, and tells packager to download if from Odoo Apps.

Also, pay attention on spaces. It is important when you deal with YAML files

But mentioned addons has extra dependencies, thus we have to specify them manually:

addons-list:
    - partner_contact_birthdate

    # Addons from Odoo Apps
    - name: bureaucrat_helpdesk_lite
      odoo_apps: true
    - name: generic_request
      odoo_apps: true
    - name: generic_mixin
      odoo_apps: true
    - name: generic_tag
      odoo_apps: true
    - name: crnd_web_list_popover_widget
      odoo_apps: true
    - name: crnd_web_diagram_plus
      odoo_apps: true
    - name: crnd_web_tree_colored_field
      odoo_apps: true
    - name: crnd_wsd
      odoo_apps: true
    - name: crnd_service_desk
      odoo_apps: true
git-sources:
    - oca: partner-contact

The example above, have to be working. It explicitly lists all dependecies.

It is design decision to require explicitly mention all required addons in assembly.
Working this way allows to keep repository small and avoid unneed dependecies added implicitly.

6. Adding other modules that could not be updated automatically

In some cases, it may be required to add module that is not available in any git repository (yet).

In this case, there are two strategies.

First one is to create separate git repository to store such modules. The benefits of this way, is that you can easily controll all your third-party addons and their changes. Something updated, then just deliver update to this repo. The only requirement is to follow branch naming guidelines: all stable branches have to be named same as odoo versions and all chages have to go through temporary dev branches named <stable branch>-<feature name>. In this case, addons from such repo could be connected in the way described in 4.

The second way, is to copy such addons directly in assembly repository in custom_addons folder. The benefit of this way - you do not need to create one more repo. The drawback of this way, is mix of automatically managed addons and manually managed addons in same repository.

7. Adding module from private git repository

Working with private repository will require from you little more efforts, then described in previous way.

Connecting private repository to assembly will require following steps.

At first, if possible, you have to generate new access token to access your private repo. This is for security reason. If possible, do not use your passwords when connecting private repositories to assembly. See docs how to create Project Access Token for GitLab repos, and How to create Personal Access Token for GitHub. The scope of generated access tokens have to allow to read your private repository.

Next you have to add your private repo as git source to odoo-packager.yml file. Note, that no credentials specified in packager file. The credentials have to be specified via environment variables later in next steps. Also, take attention and name param on git source. It is used to identify repository, to bind access credentials to this repo.

git-sources:
    - url: https://github.com/my/private-repo.git
      name: my_private_repo

In this example, we have added git source in usual way, except defining it's name.

Next, we have to bind access credentials to this git source. To achieve this we have to define two specific CI environment variables in the repository.
Check this guide, that describes how to add CI environment variables via UI to assembly.

We have to add following variables: PACKAGER_GIT_USER_my_private_repo, PACKAGER_GIT_PASS_my_private_repo. Pay attention on names of these variables. The names consist of two parts: variable name and git source name. As value for first variable we have to use username that have to be used to access your private repo. The user name, depends on credentials used. See documentation of the usage of generated access token (clonning repo via https). The value of second variable, have to be password to access repo. In case, when you have generated access toke, then this is place to insert generated access token in.

After all this done, you can just mention module name from your private repo in the addons list, and it will be automatically fetched from your private repo.

The only requirement for private repositories is to follow branch naming convention: there must be branches named similar to Odoo versions (for example 13.0, 14.0, etc) that contains stable versions of addons. The packager will look for addons in these branches.