Bitbucket Cloud · Pipelines · Checked October 29, 2026

Bitbucket Pipelines does not clone git submodules

The build's checkout has an empty folder where the submodule should be, or a step fails with fatal: could not read Username for 'https://bitbucket.org' when it tries to fetch it. Pipelines clones only your repository in the build setup, not its submodules (Atlassian's article, Git Submodule not being cloned in the Pipeline build). You give the step a way in to the submodule's repository, and run git submodule update --init yourself, in every step that needs it: each step starts in a new container.

What changed since Atlassian's article

Its HTTPS example uses a username and an app password. Bitbucket Cloud stopped accepting app passwords on July 28, 2026; Git over HTTPS now answers "The requested URL returned error: 410".
Its SSH example uses git@bitbucket.org:. Git over SSH moves to ssh.bitbucket.org: SSH to bitbucket.org fails during brownouts from November 12, 2026, and stops on December 10 (the schedule).
It edits .gitmodules with the credentials in it. Setting the URL in the clone's own config after git submodule init does the same without changing a tracked file.

HTTPS with a repository access token

In the submodule's repository: Settings, Access tokens under Security, Create access token, with the permission Repositories: Read. Atlassian's Create an access token for a repository says that repository is the only one the token can reach. The token is shown once.
In the repository where the build runs: Repository settings, Pipelines, Repository variables, a variable SUBMODULE_URL, Secured, with the address and the token in it, the user name being x-token-auth (Using access tokens): https://x-token-auth:<token>@bitbucket.org/<workspace>/<submodule>.git. Pipelines hides secured values in the build log.
In the step's script, after the checkout:

script:
  - git submodule init
  - >-
    git config submodule.lib.url
    "$SUBMODULE_URL"
  - git submodule update

lib is the submodule's name, from [submodule "lib"] in .gitmodules, which is not always its path. git submodule init copies the URL from .gitmodules into the clone's config, the next line replaces it there, and git submodule update fetches from it. We ran these three commands with Git 2.53 on a local copy: the submodule was checked out from the replaced URL, and git status stayed clean. For several submodules, give each a token from its own repository and a line of its own.

With a wrong or expired token, Git prints remote: You may not have access to this repository… and fatal: Authentication failed (what that message covers).

SSH with Pipelines SSH keys

From the same article: in the repository where the build runs, Repository settings, SSH Keys under Pipelines, generate a key pair and copy the public key; in the submodule's repository, Repository settings, Access keys under Security, add it. That gives the build read-only access to the submodule. Then set the URL as above, on the new host:

script:
  - git submodule init
  - >-
    git config submodule.lib.url
    git@ssh.bitbucket.org:ws/lib.git
  - git submodule update

For self-hosted Linux shell, macOS and Windows runners, the article has you make your own key pair instead. If the step stops at Host key verification failed., the build does not yet trust ssh.bitbucket.org: adding its host key. The HTTPS way above does not depend on the SSH move.

See the failed command from IntelliJ IDEA

Pipeline Inbox for Bitbucket Pipelines, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, lists the pipelines of all your Bitbucket Cloud repositories in an IDE tool window. For a failed pipeline it shows the command the step failed at and that command's last lines, such as the git submodule update and Git's reason. After you add the variable or the access key there is no new commit to push: with Pro, Run again builds the same commit once more from the IDE. The list, steps and logs are free; running, re-running and stopping pipelines are Pro (US$1.50 a month, with a 30-day trial).

Get it on JetBrains Marketplace

Atlassian, Bitbucket and Bitbucket Pipelines are trademarks of Atlassian; Git is a trademark of Software Freedom Conservancy; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by any of them.

More: "command not found" · "unexpected system error" · The cache is not used · Pipelines did not run after a push · "Exceeded build time limit of 120 minutes" · "Container 'Build' exceeded memory limit." · "Container 'docker' exceeded memory limit." · "We couldn't clone the repository" · "No online runner available" · "No space left on device" · "Step exceeded processing limits" · The artifact is missing in the next step · The build passed before and fails now · Build setup takes too long · "You've run out of build minutes" · "Permission denied to update branch" · "You have reached your pull rate limit" (Docker Hub) · "There is an error in your bitbucket-pipelines.yml" · "This pipeline was paused" (deployments) · Bitbucket Pipelines plugins for IntelliJ IDEA, compared · 日本語