How to properly handle Git submodules in cloud pipelines

[AadhiraRa]

We are working on an AEM as a Cloud Service project using Azure DevOps Git as our repo, and our main AEM project includes a couple of Git submodules for shared components and clientlibs. Everything builds fine locally, but when deploying through Adobe Cloud Manager, the pipeline fails to recognize or fetch the submodules. TIA!

[SantoshSai]

Hi @AadhiraRa, 

Could you please share the error log here so we can better understand the issue and provide a more accurate solution?

[AadhiraRa]

Hi @SantoshSai,

Please refer to it as below:

Step 4/12 : Checking out repository...
Cloning into '/mnt/workspace/hprtc'...
Submodule 'ui.apps/src/main/content/jcr_root/apps/shared/clientlibs' (https://dev.azure.com/hprtc/clientlibs.git) registered for path 'ui.apps/src/main/content/jcr_root/apps/shared/clientlibs'
Cloning into '/mnt/workspace/hprtc/ui.apps/src/main/content/jcr_root/apps/shared/clientlibs'...
Submodule 'ui.apps/src/main/content/jcr_root/apps/shared/clientlibs' (https://dev.azure.com/hprtc/clientlibs.git) registered for path 'ui.apps/src/main/content/jcr_root/apps/shared/clientlibs'
fatal: No submodule mapping found in .gitmodules for path 'ui.apps/src/main/content/jcr_root/apps/shared/clientlibs'
fatal: error while fetching submodule 'ui.apps/src/main/content/jcr_root/apps/shared/clientlibs'
fatal: clone of 'https://dev.azure.com/hprtc/clientlibs.git' into submodule path '/mnt/workspace/hprtc/ui.apps/src/main/content/jcr_root/apps/shared/clientlibs' failed
Failed to recurse into submodule path 'ui.apps/src/main/content/jcr_root/apps/shared/clientlibs'
fatal: No submodule mapping found in .gitmodules for path 'ui.apps/src/main/content/jcr_root/apps/shared/clientlibs'

[SantoshSai · Accepted solution]

Well, because by default, Adobe Cloud Manager doesn’t automatically initialize or update submodules during build. That means, Out of the box, Cloud Manager doesn’t run git submodule update --init, so submodules won’t be pulled unless you handle it manually.

You can add a custom build hook script in your project repo to manually initialize and update submodules as part of the build process.

Here’s how:

• In your project, create a file at .cloudmanager/hooks/pre-build.sh

• Make sure it has the following content

  #!/bin/sh
  echo "Initializing Git submodules..."
  git submodule init
  git submodule update

• Make the file executable:

  chmod +x .cloudmanager/hooks/pre-build.sh

  This script runs during the Cloud Manager pipeline execution (before the Maven build starts) and ensures submodules are pulled properly.

Make Sure .gitmodules and Submodule Commits Are Up to Date

• Double-check that your .gitmodules file is committed

• Ensure the submodule pointers are not pointing to local-only commits

• Use HTTPS URLs for submodules if Cloud Manager needs to access private repos (and ensure credentials or access tokens are handled accordingly)

Below is one of my articles where I’ve provided a sample script along with a reference to Adobe’s official documentation:

https://techinnovia.com/syncing-customer-managed-azure-devops-repo-with-adobe-cloud-manager-repo/ 

https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/usi...

Hope that helps!

[muskaanchandwani]

Hello @AadhiraRa 
Please refer to the official Documentation for Git submodule support :

https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/usi...

[AmitVishwakarma]

Hi @AadhiraRa ,
Your Cloud Manager build fails with:

fatal: No submodule mapping found in .gitmodules for path ...

This means:

  - The .gitmodules file is missing or not properly committed.

  - Submodules are not initialized automatically by Cloud Manager.

Solution:

Step 1: Ensure .gitmodules is Correct & Committed

Your .gitmodules file must exist at the root of your main repo and look like:

[submodule "ui.apps/src/main/content/jcr_root/apps/shared/clientlibs"]
    path = ui.apps/src/main/content/jcr_root/apps/shared/clientlibs
    url = https://dev.azure.com/hprtc/clientlibs.git

Make sure it's committed:

git add .gitmodules
git commit -m "Add submodule config"

Also commit the submodule reference:

git add ui.apps/src/main/content/jcr_root/apps/shared/clientlibs
git commit -m "Add submodule folder"

Step 2: Create Cloud Manager Hook to Initialize Submodules

In your project repo, create the following structure:

.cloudmanager/
└── hooks/
    └── pre-build.sh

File: .cloudmanager/hooks/pre-build.sh

#!/bin/sh

echo " Initializing Git submodules..."
git submodule init
git submodule update --recursive

Make it executable:

chmod +x .cloudmanager/hooks/pre-build.sh

This script will be executed automatically during the Cloud Manager pipeline, before Maven build starts.

Step 3: Handle Authentication for Private Submodules (Optional)

If your submodules are from private Azure DevOps repos, Cloud Manager will need access via a Personal Access Token (PAT) or deploy key.

To use HTTPS + PAT:

Update the .gitmodules URL to include the token:

[submodule "ui.apps/src/..."]
    path = ...
    url = https://<username>:<pat_token>@dev.azure.com/...

Alternatively, inject a secure token via environment variables and use a .netrc file in the hook (more secure).

Reference:

https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/usi...

Regards,
Amit