✅ Deploying Private Git Submodules on Vercel

When using private Git submodules in a project deployed via Vercel, you may encounter this warning:

Warning: Failed to fetch one or more git submodules

This happens because Vercel doesn't have access to your private submodules by default.

🔧 Solution Overview

To fix this, you'll:

1. Generate a GitHub Personal Access Token (PAT)

2. Add the token to Vercel as an environment variable

3. Configure .gitmodules to use HTTPS

4. Rewrite GitHub URLs during build to include the token

5. Update submodules before running your build command

🧪 1. Generate a GitHub Token

• Go to: https://github.com/settings/tokens?type=classic

• Click "Generate new token (classic)"

• Give it the repo scope (for private repo access)

• Set an expiration

• Copy and save the token securely

⚙️ 2. Configure .gitmodules

Make sure your submodule uses the HTTPS URL format (no token embedded):

[submodule "src/site/notes/test"]
  path = src/site/notes/test
  url = https://github.com/your-username/your-private-submodule.git

🔐 3. Add Environment Variable in Vercel

Go to Project > Settings > Environment Variables and add:

Make sure it's available in both Production and Preview environments.

🛠️ 4. Update vercel.json

Replace your buildCommand with a pre-step that rewrites GitHub URLs and fetches submodules:

{
  "outputDirectory": "dist",
  "installCommand": "npm install",
  "buildCommand": "git config --global url.\"https://${GIT_TOKEN}@github.com/\".insteadOf https://github.com/ && git submodule update --init --recursive && npm run build",
  "env": {
    "GIT_TOKEN": "@GIT_TOKEN"
  },
  "routes": [
    { "handle": "filesystem" },
    { "src": "/(.*)", "status": 404, "dest": "/404" }
  ]
}

✅ Result

After these steps:

• Vercel can clone and initialize your private submodules

• Your build includes submodule content

• Your token remains secure via environment variables

🧼 Optional Cleanup

To avoid warnings:

• Periodically rotate your GitHub tokens

• Consider limiting token scope to the specific repo or organization

• If possible, make submodules public for simpler configuration