Skip to content
This documentation applies to Codacy Self-hosted v7.0.0

For the latest updates and improvements, see the latest Cloud documentation instead.

Using submodules#

Git submodules allow you to keep a Git repository as a subdirectory within another Git repository. Git submodules are helpful in maintaining a shared configuration file for your team, and then applying it to multiple Git repositories.

Enabling submodules#

By default, Codacy does normal Git clones that don't include submodules to ensure that we only clone necessary repositories. However, if your organization needs to use submodules, please contact us at asking to enable submodules on Codacy.

After we enabled submodules for your organization, do the following:

  1. If you're using Codacy Self-hosted, you must update the license.

  2. If your submodules are:

    • Public repositories, make sure that your Git URL uses the HTTPS protocol
    • Private repositories, make sure that your Git URL uses the SSH protocol.
  3. If you already have repositories on Codacy where you want to use submodules, navigate to the page Settings and click the button Generate New User Key for each of these repositories.


    If you're using Bitbucket Cloud, you must manually add the SSH key on your user account.

    When you add a repository to Codacy, Codacy adds a new SSH key to your repository using an integration with your Git provider. Codacy uses this SSH key every time it needs to clone that repository. When you're using submodules, Codacy needs to clone additional repositories it has no access to. Since there is no way of identifying the submodules of a repository before cloning the repository, Codacy adds the SSH keys to the user account so that it has access to the same repositories as the user.

    Generate new user key

  4. If you're using submodules to share an analysis tool configuration file across your repositories, check if your tool recursively searches the subdirectories of your repositories for configuration files.

    If your tool doesn't detect the configuration files in the submodule directories, you must include a configuration file directly in the root of your repositories referencing the configuration files in the submodule directories.

Using submodules on new repositories#

You must repeat steps 2 to 4 above every time you add new repositories with submodules to Codacy.

Alternatively, you can make this the default behavior for all new repositories by enabling Add project key to the user, by default in Administration, page Settings.


If you're using Bitbucket Cloud this setting must be disabled since automatically adding the user keys isn't supported.

Add project key to the user by default

Share your feedback 📢

Did this page help you?

Thanks for the feedback! Is there anything else you'd like to tell us about this page?

We're sorry to hear that. Please let us know what we can improve:

Alternatively, you can create a more detailed issue on our GitHub repository.

Thanks for helping improve the Codacy documentation.

If you have a question or need help please contact

Last modified August 24, 2021