How to use Git submodules

What submodules are for

WayHost can attach extra GitHub repositories under your main addons repo (odoo.sh-style). Each submodule folder is added to Odoo’s addons_path so modules inside it load on that branch.

Submodules are per project branch (for example main or a staging branch). Adding a submodule on one branch does not automatically add it on another.

Before you start

• The branch must already be deployed (it needs a running stack / checkout on the server).
• Only GitHub remotes are supported today.
• Open the project → choose the branch workspace → tab Submodules.

Public repositories

Use an HTTPS GitHub URL, for example:

https://github.com/OWNER/REPO.git

1. Go to the branch → Submodules → Add submodule.
2. Paste the HTTPS URL.
3. Pick the submodule’s tracked branch (WayHost lists branches from GitHub).
4. Set the folder name under addons (for example theme or extra-apps). This becomes /mnt/extra-addons/<folder> on the stack.
5. Confirm. WayHost runs git submodule add, commits, and pushes to that project branch, then updates Odoo’s addons path.

Public HTTPS remotes do not need a deploy key.

Private repositories

Private remotes must use SSH URLs, for example:

git@github.com:OWNER/REPO.git

GitHub deploy keys are one key per repository and cannot be reused across repos. WayHost therefore generates a unique key per private submodule remote.

Step 1 — Register the private remote and create a key

1. Open the project → Settings → Submodules (private keys card).
2. Paste the private Git URL (git@github.com:…) and click Add.
3. WayHost generates an ed25519 key pair for that remote and shows the public key (and fingerprint).

Step 2 — Add the public key on GitHub

1. Open the submodule repository on GitHub (not only the main addons repo).
2. Go to Settings → Deploy keys → Add deploy key.
3. Paste the public key from WayHost.
4. Leave write access off unless you intentionally need it (read-only is enough to clone).
5. Save.

Until this key is added on GitHub, adding the submodule on a branch will fail when the server tries to fetch the private repo.

Step 3 — Add the submodule on a branch

1. Open the branch workspace → Submodules → Add submodule.
2. Paste the same git@github.com:… URL you registered.
3. Choose the submodule branch and folder name.
4. Confirm. WayHost adds the submodule on that branch, pushes, and wires the folder into Odoo.

If you see an error that private submodule URLs must be registered first, complete Steps 1–2 under Settings → Submodules before adding on the branch.

Adding the same submodule on another branch

1. Deploy / open the other branch workspace.
2. Use Submodules → Add submodule again on that branch (or Sync from git if .gitmodules already lists it after a merge).
3. Private remotes only need to be registered once per project (Settings → Submodules). You do not recreate the deploy key for each branch.

Sync from git

If you added or changed submodules outside WayHost (or merged a branch that already has .gitmodules), use Sync from git on the Submodules tab so WayHost imports the current submodule list into the database and refreshes the addons path.

Removal

The UI does not remove submodules yet. Uninstall related apps in Odoo if needed, then remove the submodule with git on the branch (and clean .gitmodules) and sync again.

Checklist

• Public → HTTPS URL → Add on branch.
• Private → SSH URL → Settings → Submodules (generate key) → GitHub Deploy keys → Add on branch.
• Branch must be deployed before add.
• Repeat “Add” (or Sync) for each project branch that needs the submodule.