Git submodule are a powerful tool for separating shared library code or parts of your project that do not often receive changes. Our service natively supports submodules with share authentication.

Our service automatically attempts to clone all submodules mentioned in your .gitsubmodule file. You can read more about configuring submodules here.

For our service to successfully pull your submodule the following configuration is required:

Parent and submodule repositories must be on the same domain name

We use the same credentials for parent and submodule repositories when cloning your project, making it a requirement that you host both your parent and submodule repositories on the same service.

This means for example, that if your parent repository is hosted on bitbucket.org then your submodules must also be hosted with bitbucket, and cannot be hosted on github.com as our service will try to authenticate with github using your bitbucket credentials.

Note: While we currently require this configuration, we plan to support this functionality in the near future.

Parent and submodule repositories must be accessible using the same credentials

As mentioned above, when cloning your repository and it’s submodules we will use the same credentials to authenticate cloning both. This means that the account you’re using to clone your parent repository must also have read rights to the submodule.

This is a main cause of failed sub module clones – the account that you have configured OnCheckin to access your repository with may only have access to the parent repository, causing the submodule clone to fail.

You must configure user/pass based authentication

When configuring an OnCheckin deployment project that contain submodules you are required to use the “Git” source control provider with a static username and password.

When selecting both Github and Bitbucket OAuth based project configuration our service only grants itself read access to the main repository, as until we run our first clone we are unable to see your submodules. By accessing your account using username/password based credentials you are able to ensure that the account you’ve configured our service to use has access to all of the correct repositories manually.

You can read about configuring access to users on Bitbucket and Github using the links below:

Bitbucket - Grant users and groups access

Github – Adding collaborators to a personal repository

Configuring your project to support Submodules

To ensure that the above requirements have been met, simply follow the guide below.

Login to your OnCheckin deployment manager.

Click on the deployment project that you’d like to start cloning submodules with to open it’s configuration page. If you’re creating a new project the same applies, but instead click on the “Add new deployment configuration” button.

Note that the above project is using the Bitbucket OAuth credentials for auth.

From the “Source Control Type” drop down select “Git”.

Enter your projects https Url. An example of this would be: https://bitbucket.org/oncheckin/oncheckinexample.git

(Note: SSH urls are supported, but only with username/password authentication).

Now enter your username and password.

Press “Test source control settings”. Ensure that a success message is displayed.

You’re done! Your next deployment should now clone your submodules successfully. Your build logs will also mention and measure the durations of these clones.