Git submodules

Last updated 31st March 2021

Clone submodules during deployment

Web PaaS allows you to use submodules in your Git repository. They are usually listed in a .gitmodules file at the root of your Git repository. When you push via Git, Web PaaS will try to clone them automatically.

Here is an example of a .gitmodules file:

[submodule "app/Oro"]
    path = src/Oro
    url =
[submodule "src/OroPackages/src/Oro/Bundle/EntitySerializedFieldsBundle"]
    path = src/OroPackages/src/Oro/Bundle/EntitySerializedFieldsBundle
    url =
[submodule "src/OroB2B"]
    path = src/OroB2B
    url =

When you run git push, you can see the output of the log:

Validating submodules.
  Updated submodule git:// 4 references updated.
  Updated submodule git:// 229 references updated.
  Updated submodule git:// 11 references updated.

Error when validating submodules

If you see the following error:

Validating submodules.
  Found unresolvable links, updating submodules.

E: Error validating submodules in tree:
    - /src/Oro: Exception: commit 03567c6 not found.

   This might be due to the following errors fetching submodules:
    - HangupException: The remote server unexpectedly closed the connection.

Since the Web PaaS Git server cannot connect to Github via SSH without being granted an SSH key to do so, you should not be using an SSH URL:, but you should use an HTTPS URL instead:

Use of private git repositories

When using Git submodules that are hosted on private repositories, using the https protocol will fail with errors like:

GitProtocolError: unexpected http resp 401 for

To fix this, you need to:

1. Change your .gitmodules file from the HTTPS syntax to the SSH syntax, e.g.

[submodule "support/mymodule"]
    path = support/mymodule
    url =
[submodule "support/mymodule"]
    path = support/mymodule

2. Add the SSH public key in the Web PaaS project settings "Deploy Key" tab in the Web UI as per the Private Repository documentation page, which will allow our Git service to pull the module from the remote git service. This assumes you have configured the remote git repository to allow this by generating a private/public key pair. For example, see the Bitbucket documentation.

Removing submodules

These steps are not specific to Web PaaS, but kept as a reference for Git so that submodules are effectively removed prior to entering the build process.

1. Delete information for the submodule you'd like to remove from .gitmodules.

2. Stage changes to .gitmodules:

$ git add .gitmodules

3. Remove the submodule's configuration from .git/config.

4. Remove the submodule from the repository (without trailing slash):

$ git rm --cached path_to_submodule

5. Remove the submodule's files in .git from the repository (without trailing slash):

$ rm -rf .git/modules/path_to_submodule

6. Commit the changes:

$ git commit -m "Removed submodule."

7. Remove the submodule code locally, now untracked:

$ rm -rf path_to_submodule

Original can be found in a gist by Mahdi Yusuf, replicated here for internal linking.

Did you find this guide useful?

Please feel free to give any suggestions in order to improve this documentation.

Whether your feedback is about images, content, or structure, please share it, so that we can improve it together.

Your support requests will not be processed via this form. To do this, please use the "Create a ticket" form.

Thank you. Your feedback has been received.

These guides might also interest you...

OVHcloud Community

Access your community space. Ask questions, search for information, post content, and interact with other OVHcloud Community members.

Discuss with the OVHcloud community

In accordance with the 2006/112/CE Directive, modified on 01/01/2015, prices incl. VAT may vary according to the customer's country of residence
(by default, the prices displayed are inclusive of the UK VAT in force).