Git Submodule not being cloned in Bitbucket Pipeline build

Platform Notice: Cloud Only - This article only applies to Atlassian apps on the cloud platform.

Summary

You run Pipelines builds on a Bitbucket Cloud repository. This repo has as a submodule another Bitbucket repo, but the submodule is not cloned in the Build setup of the Pipelines build.

Cause

  • Bitbucket Pipelines do not clone a submodule during the Build setup of a step. You will need to configure authentication details and initialize the submodule in a step's script.

  • If you have already configured authentication details and cloning the submodule fails, you may have missed something in your configuration. Check the Solution section below to see if you have followed all the necessary steps.

Solution

Assume that the repo where the Pipelines build runs has a .gitmodules file like the following:

[submodule "xyz"] path = xyz url = git@bitbucket.org:my-workspace/my-submodule.git branch = main

You can configure your Pipelines step to clone a submodule using either HTTPS or SSH.

Clone a submodule with HTTPS

You will first need to configure authentication details. You can use the Bitbucket username and app password of an account that has access to the submodule.

  1. You can find the username of the Bitbucket account on this page, after logging in: https://bitbucket.org/account/settings/.

  2. You can generate an app password for this account with Repositories - Read permissions from the page https://bitbucket.org/account/settings/app-passwords/.

  3. Create two secured repository variables (in the repo where the build runs) named e.g. USERNAME and PASSWORD and store the values of the Bitbucket username and app password, respectively. You need to have admin access to the repo to create the variables.

You will then need to adjust your step's script in the bitbucket-pipelines.yml to adjust the submodule URL and initialize the submodule.  This needs to be done on every Pipelines step where you want the submodule to be cloned.

Builds that use Atlassian's infrastructure or a self-hosted Linux Docker, Linux Shell, or MacOS runner

Adjust the step where you want to initialize the submodule as follows:

image: atlassian/default-image:4 pipelines: default: - step: script: - git config --file=.gitmodules submodule.xyz.url https://$USERNAME:$PASSWORD@bitbucket.org/my-workspace/my-submodule.git - git submodule update --init

Replace xyz, my-workspace, and my-submodule in the script with your respective values for your submodule.  If you named your variables something other than USERNAME and PASSWORD, replace those as well with the names of your variables.

Builds that use a self-hosted Windows runner

Adjust the step where you want to initialize the submodule as follows:

pipelines: default: - step: script: - git config --file=.gitmodules submodule.xyz.url https://$($env:USERNAME):$($env:PASSWORD)@bitbucket.org/my-workspace/my-submodule.git - git submodule update --init

Replace xyz, my-workspace, and my-submodule in the script with your respective values for your submodule.  If you named your variables something other than USERNAME and PASSWORD, replace those as well with the names of your variables.

Clone a submodule with SSH

Builds that use Atlassian's infrastructure or a self-hosted Linux Docker runner

You can use Bitbucket Pipelines SSH keys to set up access to the submodule. You need to have admin access to the repo where the build runs and to the submodule to perform the following steps.

  1. Open the repository where the build runs on Bitbucket's website.

  2. Select Repository settings from the left sidebar.

  3. Select SSH Keys (under the section Pipelines) from the new left sidebar.

  4. On this page, either select Generate keys to generate an SSH key pair, or add your own SSH key pair.

  5. Select Copy public key.

Afterwards:

  1. Open the submodule repository on Bitbucket's website.

  2. Select Repository settings from the left sidebar.

  3. Select Access keys (under the section Security) from the new left sidebar.

  4. Select Add key, give a label to the key, and in the Key field, paste the public SSH key you copied earlier.

  5. Select Add SSH key.

This access key will give your Pipelines build read-only access to the submodule.

You will then need to adjust your step's script in the bitbucket-pipelines.yml to adjust the submodule URL and initialize the submodule.  This needs to be done on every Pipelines step where you want the submodule to be cloned. You can adjust the step as follows:

image: atlassian/default-image:4 pipelines: default: - step: script: - git config --file=.gitmodules submodule.xyz.url git@bitbucket.org:my-workspace/my-submodule.git - git submodule update --init

Replace xyz, my-workspace, and my-submodule in the script with your respective values for your submodule. 

Builds that use a self-hosted Linux Shell, MacOS, or Windows runner

Bitbucket Pipelines SSH Keys are supported for these types of runners, so you will need to generate your own SSH key pair. To perform the following steps, you need to have admin access to the repo where the build runs and to the submodule.

  1. Generate an SSH key pair on your computer. A sample command to do this is the following:

    • ssh-keygen -t rsa -b 4096 -N '' -f ~/.ssh/my_ssh_key

  2. Copy the content of the public key you generated. If you used the sample command from Step 1, the SSH key pair will be located at ~/.ssh/ and the public key will be named my_ssh_key.pub.

  3. Open the submodule repository on Bitbucket's website.

  4. Select Repository settings from the left sidebar.

  5. Select Access keys (under the section Security) from the new left sidebar.

  6. Select Add key, give a label to the key, and in the Key field, paste the public SSH key you copied in Step 5.

  7. Select Add SSH key.

Afterwards:

  1. On your computer, encode the SSH key pair's private key to base64. If you used the sample command from the previous steps to generate the SSH key pair, the SSH key pair will be located at ~/.ssh/ and the private key will be named my_ssh_key.

    1. On Linux, you can encode it with the command:

      • base64 -w 0 ~/.ssh/my_ssh_key

    2. On MacOS, you can encode it with the command:

      • base64 -i ~/.ssh/my_ssh_key

    3. On Windows PowerShell, you can encode it with the command:

      • [convert]::ToBase64String((Get-Content -path "~/.ssh/my_ssh_key" -Encoding byte))

  2. Copy the encoded value from your terminal or PowerShell.

  3. Open the repository where your build runs on Bitbucket's website.

  4. Select Repository settings from the left sidebar.

  5. Select Repository variables (under the section Pipelines) from the new left sidebar.

  6. On this page, create a secured variable named e.g. SSH_KEY and paste in the value the encoded private key you copied before.

You will then need to adjust your step's script in the bitbucket-pipelines.yml to adjust the submodule URL and initialize the submodule.  This needs to be done on every Pipelines step where you want the submodule to be cloned.

 If your step runs with a self-hosted Linux Shell or MacOS runner, you can adjust it as follows:

pipelines: default: - step: script: - (umask 077 ; echo $SSH_KEY | base64 --decode > ./id_rsa) - git config --file=.gitmodules submodule.xyz.url git@bitbucket.org:my-workspace/my-submodule.git - GIT_SSH_COMMAND="ssh -i ./id_rsa" git submodule update --init

Replace xyz, my-workspace, and my-submodule in the script with your respective values for your submodule.  If you named your variable something other than SSH_KEY, replace that as well with the name of your variable.

 

If your step runs with a self-hosted Windows runner, you can adjust it as follows:

pipelines: default: - step: script: - git config --file=.gitmodules submodule.xyz.url git@bitbucket.org:my-workspace/my-submodule.git - ([Text.Encoding]::ASCII.GetString([Convert]::FromBase64String($Env:SSH_KEY))) | Out-File -Encoding "ASCII" id_rsa - $Env:GIT_SSH_COMMAND='ssh -i ./id_rsa' - git submodule update --init

Replace xyz, my-workspace, and my-submodule in the script with your respective values for your submodule.  If you named your variable something other than SSH_KEY, replace that as well with the name of your variable.

 

 If you still experience issues cloning the submodule in your Pipelines build, raise a Support Ticket and share the Pipeline build URL from bitbucket.org

Updated on September 25, 2025
Platform
Cloud only
App
Bitbucket Cloud
On this pageSummarySolution

Still need help?

The Atlassian Community is here for you.
Ask the Community