oca-port-jarsa

oca-port-jarsa is a Jarsa-maintained fork of the original oca-port tool.

It is designed for enterprise Odoo migrations using both GitHub and GitLab repositories, with automatic platform detection, GitLab Merge Request support and native integration with pre-commit-vauxoo.

Key Features

• Automatic SCM detection (GitHub / GitLab) using remote URL
• Native GitLab Merge Request lookup (gitlab.com and self-hosted)
• Native GitHub Pull Request lookup
• Automatic hook selection:
  • pre-commit for GitHub projects
  • pre-commit-vauxoo for GitLab projects
• Automatic hook installation for GitLab using pre-commit-vauxoo --install
• Multiple GitLab instances supported (per-domain tokens)
• pipx-ready installation
• CI/CD friendly
• JSON output compatible with original oca-port

Platform Auto Detection

The platform is automatically detected using the target remote URL:

Manual override is also available:

oca-port-jarsa --platform gitlab ...
oca-port-jarsa --platform github ...

Installation

Using pipx (recommended)

pipx install oca-port-jarsa

Development installation

git clone https://github.com/Jarsa/oca-port-jarsa.git
cd oca-port-jarsa
pipx install .

Authentication Setup

GitHub Token

Used only when operating on GitHub repositories.

export GITHUB_TOKEN=ghp_xxxxxxxxx

GitLab Tokens (multi-instance support)

oca-port-jarsa supports multiple GitLab instances using domain-based environment variables.

Define tokens in your shell:

export GITLAB_TOKEN_GITLAB_COM="xxxx"
export GITLAB_TOKEN_GIT_JARSA_COM="xxxx"
export GITLAB_TOKEN_GIT_VAUXOO_COM="xxxx"

Naming rule:

GITLAB_TOKEN_<DOMAIN>

Where:

https://git.jarsa.com  -> GITLAB_TOKEN_GIT_JARSA_COM
https://git.vauxoo.com -> GITLAB_TOKEN_GIT_VAUXOO_COM
https://gitlab.com     -> GITLAB_TOKEN_GITLAB_COM

Usage

Basic syntax

oca-port-jarsa <source> <target> <module_path> [options]

Example — Migration preview (dry run)

oca-port-jarsa origin/16.0 origin/18.0 stock_move_auto_assign --dry-run --verbose

Execute migration

oca-port-jarsa origin/16.0 origin/18.0 stock_move_auto_assign

Custom destination branch

oca-port-jarsa origin/16.0 origin/18.0 stock_move_auto_assign \
--destination jarsa-dev/18.0-mig-stock_move_auto_assign

Using subfolder modules

oca-port-jarsa origin/main origin/18.0-mig \
--source-version=16.0 \
--target-version=18.0 \
./addons/custom/MY_MODULE \
--destination jarsa-dev/18.0-mig-MY_MODULE

Hook Execution Behavior

GitHub projects

Uses the standard pre-commit workflow:

pre-commit install
pre-commit run

GitLab projects

Uses Vauxoo workflow:

pre-commit-vauxoo --install
pre-commit-vauxoo

Existing PR / MR Detection

GitHub

Automatically searches existing Pull Requests using GitHub API.

GitLab

Automatically searches open Merge Requests:

• Target branch match
• Module name match
• Supports gitlab.com and self-hosted instances

Migration Mode

Exit codes:

JSON Output API Mode

import json
import oca_port

app = oca_port.App(
    source="origin/16.0",
    target="origin/18.0",
    addon_path="stock_move_auto_assign",
    repo_path="/home/odoo/repos/stock-logistics-warehouse",
    output="json",
    fetch=True,
    github_token="<GITHUB_TOKEN>",
)

result = app.run()
data = json.loads(result)

print(data)

Release Flow

git tag v1.0.0
git push origin v1.0.0

Origin

Based on the original OCA tool: https://github.com/OCA/oca-port

Maintained by Jarsa Sistemas.