How do I handle authenticating to private submodules

If you’re deploying to private submodules, you’ll want to keep a few things in mind.

Step 1: Authenticate to your private submodule using SSH URLs

You must use an SSH URL to authenticate. You cannot use an HTTPS URL to authenticate to your private submodule. The SSH URLs should be included in your .gitmodules file. Otherwise, DeployBot will not be able to connect. 

Note: If you receive an error message that says, “no credentials provided” that means it’s likely you’re using an HTTPS URL and not SSH.

Step 2: Add the public submodule key to your repository

If your submodules are protected repositories, use the “public key for submodules” to authenticate to these repositories. You can find this key by going to Repository > Settings and scroll to the bottom of the page. 

You can configure deployment key or just a regular key with read-only permissions in your repository hosting service. 

Step 3: Create a dedicated user for deployments

This is an important step. Add the DeployBot public SSH key for submodules to your user and allow them access to the necessary repositories. A dedicated user will resolve many common permission issues with submodules. 
If you’re a GitHub user, visit GitHub to learn more about their recommendations for dedicated users.

 Common issues with Submodules

I changed the repository URL from HTTPS to SSH. But my deployment still fails. What’s going on?

If you’re still receiving an error after changing your submodule URLs to SSH try deploying again using the “redeploy from scratch” option. DeployBot will then take everything in the repo and deploys it to the end destination. You can enable this option on the deployment screen.

DeployBot couldn’t update the submodules for my repository. How do I fix this?

What we recommend: 
  • Please check if all the repositories used as submodules allow DeployBot to access them. Please see step 2 in the section above. 
  • Make sure that your main repository links to commits in submodules that are currently present.
  • If submodule repository was rebased or commits were deleted from it, you may need to update your main repository with a link to a new commit.

While trying to checkout my repository for a deployment a submodule failed to update.

What we recommend:
  • Check to see if your submodules are requiring authentication to access. 
  • Make sure that you can make a clone of the repository and initialize all the submodules. Very often this problem is caused by submodules which were not deleted correctly from the repository.

I added the DeployBot key to my Github repository but it says the key is already in use. How do I fix this?

In this scenario, it’s likely that you’re trying to authenticate to two or more repositories with the same key. GitHub recommends creating a specific user for this type of setup. This “machine”  account can have its own set of keys. Usually, there's a main repository and secondary repositories. 
What we recommend:
  1. Create a separate GitHub user, just for deployments. See step 3 in the section above. 
  2. Move your key from the main repository to that user. 
  3. Give that user access to all the repositories you need to deploy. 
This process is a bit involved, but this is how GitHub recommends handling these situations.
Note: This is not to be confused with a deployment key. This is for authenticating to the repo itself, not necessarily what we call a “deployment key".

Still need help? Contact Us Contact Us