Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

Bitbucket Pipelines and git submodules

Gediminas Šedbaras July 20, 2016


How can I make Pipelines work when my repo contains git submodules that need to be initialized before the build is started?

8 answers

13 votes
Jacob Ideskog August 31, 2017

This seems fixed now with the SSH keys available in pipelines.


1. Create an SSH keypair for the repo that runs the pipeline that needs to init a submodule


2. Add the public key to the submodule repo.


3. add `git submodule update --init` to your pipeline script

sofrito December 27, 2017

Works. Thanks.

Like mcw likes this
Gijs Wobben March 12, 2018

Works perfectly! Thanks!

Like mcw likes this
tri.nm May 16, 2018

It works. Thanks !

As a note, you should remove 


from your git path in your git commands inside your pipeline script.

Because only the ssh key is enough for authentication. 

Like # people like this
mcw August 26, 2019

This worked for me as well. 

To be clear, add the public key as an Access Key in the `submodule` repo.

Like Byron Appelt likes this
5 votes
sunnywcwong April 18, 2017

It surely is a "massive missing feature in BB Pipelines". After 9 months passing by, is this fixed now? or is it still a manual submodule update?

5 votes
romanas667 July 25, 2016

That isn't enough.

If your submodules point at an ssh Bitbucket url (, you need to change the url of the submodule as well. I did it like this:


git config --file=.gitmodules submodule.$SUBMODULENAME.url https://$USERNAME:$

Then it's the standard git submodule update --init.

This feels like a massive missing feature in BB Pipelines and I hope it gets resolved in future updates!

5 votes
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
July 20, 2016

you'll need to reconfigure the git remote to pull from Bitbucket. Pipelines uses an O-auth token to do the initial cloning which is then destroyed immediately afterwards.

First you'll want to create an app-password for the user who's going to access the submodules (App passwords are here in Bitbucket Cloud | Bitbucket Blog). This will ensure you can work with 2fa enabled on the account.

Then you'll need to provide the username and app-password as Bitbucket Pipelines variables (

assuming you've named them USERNAME and PASSWORD, add this step to the start of your pipeline:

git remote set-url origin https://$USERNAME:$

followed by initialising your submodules

git submodule update --init
kenken17 August 19, 2016

Hi I have tried 20+ times but until the `git submodule update --init` step, it always said:

+ git submodule update --init
Submodule 'dev/scripts/api' ( registered for path 'dev/scripts/api'
Cloning into 'dev/scripts/api'...
Warning: Permanently added '' (RSA) to the list of known hosts.

Permission denied (publickey).

fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
fatal: clone of '' into submodule path 'dev/scripts/api' failed


Anyone has experienced this?


Michael Dahlke April 3, 2017

Did you solve this issue?


I'm running into the same problem :(

NissimPradhan May 17, 2017

Please note that, the environment variable $USERNAME mentioned by Sebastian should be account username instead of the app password username. The password should be the password from one of the app passwords you've created in account settings.

Thilak Rao October 27, 2018
Like Karim Heraud likes this
Mike Medved February 20, 2019

I've added SSH keys from the pipeline repo to my submodule bitbucket repos, but I continue to get this error when trying to do a submodule update

fatal: could not read Username for: No such device or address

Seems clearly related, help?

Like Vinay Kumar likes this
Mike Medved February 20, 2019

note that was up in the fatal line, but Atlassian communities kept barfing on it, even in code or block quote.  Sup with that?

Shawn Chan June 10, 2021

just spent a whole afternoon looking into this... the answer provided by Jacob Ideskog does work. However, one important point is to make sure the module url in`.gitmodules` is something like but not using https:. Only when it's set toSSH it will pick up the public key you generated and added to the submodule's repo. Otherwise, it will complain about either the username or password cannot be found.

Hope this helps 

1 vote
Yashvit November 13, 2019

I followed the steps shown on this:

Managed to get the git submodule checkout working fine.

Only issue is, we use IP Whitelisting for our Bitbucket Account. When that is enabled, the submodule checkout fails! 

Warning: Permanently added the RSA host key for IP address '' to the list of known hosts.

To access this repository, an admin must whitelist your IP.

fatal: Could not read from remote repository.

I tried whitelisting this IP and a bunch of others that it uses, but no luck! 

Anyone has managed to get a workaround for this? 

Carl Cook June 6, 2022

Same problem here. Did you have any luck fixing the problem? I'll raise a ticket otherwise.

1 vote
Soeren Balko August 14, 2017

Atlassian, this needs urgent fixing! I thought the advantage of using Bitbucket pipelines over some external CI system was the better integration with Bitbucket. Turns out that's not the case. Sad!

0 votes
Simon February 10, 2020

I would also like to use a submodule in my pipeline.
The submodule has been initilaised, but unfortunately

git submodule update --init

fails with the error:

fatal: destination path '<pathToSubmodule>' already exists and is not an empty directory,

because during the build setup the node_modules were already loaded from the cache.
Is there a solution for this?

Valerii Kulyk, May 12, 2020

use git submodule update --init --force

Simon December 1, 2020

Hi @Valerii Kulyk,
thanks for you answer, but this is not working. I still get the same error.

The --force option only causes the submodule to be cloned with git checkout --force, but does not fix the error that the submodule's folder is not empty.

0 votes
Brian Maissy July 9, 2018

For anyone else who found this thead and thinks this is a serious oversight, you can vote on the issue here

Suggest an answer

Log in or Sign up to answer
AUG Leaders

Atlassian Community Events