This documentation is a preview of the pull request #2301

For the latest updates and improvements in production, open docs.codacy.com 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.

By default, Codacy does normal Git clones that don't include submodules to ensure that we only clone necessary repositories. If your organization needs to use submodules, you can request Codacy to enable this feature for you.

Important

GitHub only: Your repository and the repositories that you add as submodules must belong to the same GitHub organization.

Prerequisites for using submodules#

Contact us at support@codacy.com asking to enable submodules on Codacy.
If you're using Codacy Self-hosted, update your license.
Make sure that your Git URL uses the correct protocol:
- GitHub: HTTPS protocol
- GitLab and Bitbucket:
  - HTTPS protocol, if your submodules are public repositories
  - SSH protocol, if your submodules are private repositories

Enabling submodules on a repository#

When using submodules, you must do the following for all your existing and new repositories:

GitLab and Bitbucket only: Update the public SSH key that Codacy uses to access your repository.
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.

Updating the public SSH key to access the repository#

This section applies only to GitLab and Bitbucket

On GitLab and Bitbucket organizations, Codacy generates a repository key when you add a repository to Codacy and uses it to clone that repository. When you're using submodules, Codacy needs to clone additional repositories it may not have access to. To overcome this, Codacy must use an SSH key of your user account to have access to the same repositories as your user.

To update your GitLab or Bitbucket public SSH key that Codacy uses to access your repository, do the following:

Open the repository Settings, tab General. In the Danger zone area, you have the SSH Key generated by Codacy to access your repository.
Depending on your Git provider, do the following to update the key:
- For GitLab, click the button Generate New User Key. Codacy removes the existing repository key and creates the new SSH key on your user account automatically.
- For Bitbucket:
  1. Remove the existing Codacy key from the repository settings on your Git provider.
  2. Click the link Add new user key. This takes you to the Git provider page where you can manage your user account SSH keys.
  3. Add a new SSH key to your Git provider account.

Automating user keys for new repositories#

This section applies only to Codacy Self-hosted

You can set Codacy to automatically add the new SSH key to your Git provider account for all new repositories by enabling Add project key to the user, by default on the Administration console, page Settings.

Important

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

Add project key to the user by default

Using submodules#

Prerequisites for using submodules#

Enabling submodules on a repository#

Updating the public SSH key to access the repository#

Automating user keys for new repositories#

See also#

Share your feedback 📢