Addon Repositories

Addon repositories let you include extra Odoo modules in your projects. These are Git repositories containing custom addons: your organization's proprietary modules, community addons from OCA, or the official Odoo Enterprise repository.

Repository Hierarchy

Addons come from several levels. Each level supplies repositories that end up in your environments:

How Repos Flow Down

1. Platform addons and organization addons are offered to projects. A project uses one only after it is selected under Shared addons on the project's Repositories tab.
2. Project addons are the project's own extra repositories. They are included in every environment of the project.
3. Module repositories (legacy) are an older way to attach repos with a branch-mapping rule, such as dev → develop and production → main. Environment overrides do not apply to them.
4. Environment overrides let you exclude a shared addon or project addon, or pin a different branch, for one environment without affecting the rest.

How Selection Works

• Shared addons are chosen per project. An organization or platform addon deploys to a project's environments only when that project has it selected.
• New projects start with the default addons. Every organization addon marked as a default is selected when a project is created.
• New organization addons usually need to be added per project. A new addon is added automatically only to projects with no saved addon selection. Most projects have one: it is saved when the project is created with default addons, or when anyone changes it. If a project does not have a new addon, open the project's Repositories tab: the addon is listed under Available in your organization, and Add selects it.
• Environment overrides only adjust selected addons. An override can exclude an addon or change its branch for one environment. It cannot add an addon the project has not selected.
• Overrides with no effect. If an environment has an override for an addon that the project no longer selects, or that has been disabled, the environment's Repos tab lists it under Overrides with no effect. It changes nothing. Select the addon under Shared addons to make the override apply again, or click Remove and then Save overrides to delete it.

Addon Tiers

OEC.sh organizes addon repositories in three tiers:

1. Platform addons: Offered to all organizations (managed by portal admins)
2. Organization addons: Offered to every project in your organization. Each project selects the ones it uses.
3. Project addons: Specific to a single project

When the same addon exists at multiple levels, project-level takes priority over organization, and organization takes priority over platform.

Adding an Addon Repository

Add Organization Addon Repository

If you have Git connections configured, use the smart selection workflow:

1. Go to Settings > Addon Repos tab
2. Click Add Addon
3. Step 1: Select a Git connection
4. Step 2: Select a repository from your connection
5. Step 3: Select a branch
6. Step 4: Configure details (name is auto-filled)
7. Click Save

The slug is automatically generated from the repository name.

Alternative: Enter URL Manually

If you prefer to enter the repository URL directly, or don't have Git connections:

1. Click Enter URL manually instead (or if no connections exist, this is shown by default)
2. Enter the Git repository URL (e.g., https://github.com/org/repo.git)
3. Enter the Git branch name
4. Fill in the name and optional description
5. Toggle Public repository if no authentication is needed
6. Click Save

Add Project-Specific Addon Repository

1. Open your project
2. Go to the Repositories tab
3. Find Project Addons
4. Click Add Repository (or Upload module (.zip) for a module archive)
5. Enter the repository details:
   • Git URL: The repository URL
   • Branch: The Git branch to use
   • Priority: Controls loading order (lower = higher priority)
6. Click Save

Repository Settings

Each addon repository has these settings:

• Name: A display name for the repository
• Slug: Auto-generated URL-friendly identifier (locked after creation)
• Description: Optional description
• Git URL: The repository URL
• Branch: The Git branch to use
• Priority: Loading order (default: 100, lower values load first)
• Public/Private: Toggle based on repository visibility
• Install Dependencies: Enable to install requirements.txt and apt.txt

Repository Status

Each repository shows a status indicator:

• Active (green dot): Projects that select the repository get it on their next deploy

Click the disable icon to stop offering a repository without deleting it. Disabled repositories disappear from the list and stop deploying everywhere. To turn one back on, click Add Addon and add it again with the same slug. Projects that had it selected get it back on their next deploy, together with any environment overrides they had for it.

Selecting Addons for a Project

Projects can choose which platform and organization addons to include:

1. Open your project
2. Go to the Repositories tab
3. Find the Shared addons section
4. Click Browse Addons to open the selection modal
5. Use the search and filter options to find addons
6. Select the addons you want to include
7. Click Apply to save your selections

Selected addons will be included in the next deployment of every environment in the project. You can also change the selection from an environment's Repos tab; it still applies to the whole project.

How Addons Are Deployed

During deployment, OEC.sh clones all selected addon repositories, installs Python and system packages listed in requirements.txt and apt.txt, and makes the addons available in Odoo's Apps menu.

Per-Environment Addon Overrides

By default, every environment gets the project's selected shared addons and its project addons. You can exclude one of them, or change the branch it uses, for a single environment. Overrides cannot add an addon the project has not selected (see How Selection Works).

Excluding Addons from an Environment

1. Go to your Environment > Repos tab
2. Find the addon under Environment overrides
3. Toggle the switch to OFF
4. Click Save overrides
5. Click Deploy to apply the change

Branch Overrides per Environment

Override the branch for specific addon repositories per environment:

1. Go to your Environment > Repos tab
2. Find the addon under Environment overrides
3. Click its branch box
4. Select a different branch (e.g., 19.0-dev instead of 19.0)
5. Click Save overrides
6. Click Deploy to apply the change

Common Scenarios:

• Production: Use stable branches (e.g., 19.0, main)
• Staging: Use release candidate branches (e.g., 19.0-rc, staging)
• Development: Use development branches (e.g., 19.0-dev, develop)

Viewing Environment-Specific Configuration

The Environment overrides section of the Repos tab shows:

• Addons: The project's selected shared addons and its project addons
• Toggle status: ON (included) or OFF (excluded) for this environment
• Branch: The branch this environment uses, with "Overrides default" when it differs from the default
• Overrides with no effect: Saved overrides for addons the project does not select. They change nothing until the addon is selected again.

Managing Dependencies

Addon repositories can include dependency files:

• requirements.txt: Python packages to install
• apt.txt: System packages to install

Enable the Install dependencies from this repository option when adding a repository to have these installed automatically during deployment.

Removing an Addon Repository

Remove from Organization

1. Go to Settings > Addon Repos
2. Find the repository you want to remove
3. Click the delete icon
4. Confirm the deletion

Remove from Project

1. Open your project
2. Go to the Repositories tab > Project Addons
3. Click the delete icon next to the repository
4. Confirm the deletion

Note: Removing a repository requires redeployment for changes to take effect. Uninstall any installed addons from Odoo first to avoid errors.

Private Repository Authentication

For private repositories:

1. First set up a Git connection in Settings > Git Connections
2. When adding the addon repository, the smart selection workflow uses your connection automatically
3. For manual entry, disable the "Public repository" toggle and select your connection
4. The connection provides authentication during deployment

See the Git Connections guide for details on setting up authentication.

Connecting Odoo Enterprise

The odoo/enterprise repository is private and hosted under the odoo GitHub organization, which has OAuth App access restrictions enabled. This means GitHub OAuth connections (the default "Connect with GitHub" flow) will be blocked with a 403 error when trying to clone Enterprise, even if your account has an active Odoo Enterprise subscription.

Use a Personal Access Token instead:

1. Log in to GitHub with the account that has Odoo Enterprise access
2. Go to Settings → Developer settings → Personal access tokens → Tokens (classic)
3. Click Generate new token (classic)
4. Set a name (e.g. oecsh-enterprise), choose an expiration, and tick the repo scope
5. Copy the token (starts with ghp_)
6. In OEC.sh, go to Settings → Git Connections → Add Git Connection
7. Choose GitHub → Personal Access Token, paste your token, and save
8. Use this PAT-based connection when adding the odoo/enterprise addon repository