Git Submodules

Last Updated March 2015

If you use Git submodules in your app, we load submodules into your app on deploy based off what's in your .gitmodules file. There's a few things to know when using submodules on Pagoda Box. After reading this doc, you should be familiar with:

  • Adding submodules
  • Using public & private submodules

Using Submodules Will Increase Deploy Times

Using Git submodules will increase the time it takes your app to deploy. On each deploy, entire submodule(s) must be dowloaded and packaged with your code.

Adding Submodules

Adding submodules is very easy. You just need the clone URL of the repo you'd like to add as a submodule.

Adding Submodules Terminal

  $ git submodule add submodule_clone_url
  $ git submodule init

The init command registers the submodule to your repo so any of your collaborators who pull will get the contents of the submodule instead of just the folder.

HTTPS vs SSH Submodule Clone URLs

The majority of hosted Git submodules provide both HTTPS and SSH clone URLs. Below are example clone urls for the a project on Github:

HTTPS:  https://github.com/username/project.git
SSH:    git@github.com:username/project.git

Depending on which you use, there may be some additional setup to get them to function properly.

HTTPS Clone URLs (Recommended)

When using HTTPS clone URLs to pull submodules from a 3rd party, Git attempts to pull the submodules through a secure HTTP connection. This doesn't require an SSH handshake and should allow you to clone public repos without issue.

Using HTTPs clone URLs to load private submodules isn't recommended. In order to authenticate correctly, you have to include your 3rd party username/password or an API auth token in the clone URL.

SSH Clone URLs

When using SSH clone URLs to pull submodules from a 3rd party, Git attempts to pull the submodules using SSH, whether it's a public or private repo. The SSH handshake requires matching SSH keys on both ends. In order for the handshake to work, you must first add your app's SSH key to your 3rd party user account. This will allow the clone requests to authenticate correctly during the deploy process.

Using Private Submodules

To use private git submodules, you'll need to grant your app access to pull that repo on deploy. You can do this by adding your app's public SSH key to your user account on your 3rd party service. If your submodule is hosted on your own Git server, you can add your app's Public SSH Key as a deploy key.

Your app's SSH key can be found under Dev Config > Public SSH Key. Once added, this SSH key will be used to grant your app access to pull the submodule on deploy. More information can be found in the App SSH Keys doc.

If you have any questions, suggestions, or corrections, let us know.