Skip to main content
Git submodules embed one repository inside another while keeping separate version histories, giving Blitzy unified access to your full multi-repo architecture.
Jump to: Why Submodules | Setup | Updating | Read-Only Submodules | Troubleshooting

​
Why Use Submodules

  • Unified context - Blitzy sees all your repositories as one codebase
  • Modular architecture - Keep separate repos while enabling coordinated changes
  • Cross-repo awareness - Blitzy understands dependencies and relationships across your system

​
Setup

1

Grant Blitzy access

Grant Blitzy access to the parent repository and every repository in your .gitmodules file through your source control integration settings.
2

Add submodules

git submodule add <repo-url> <path>
Use absolute HTTPS URLs, not SSH. Skip this step if submodules are already configured.
3

Verify .gitmodules

Confirm entries use absolute HTTPS URLs with branch tracking:
[submodule "shared-lib"]
  path = shared-lib
  url = https://your-host.com/your-org/shared-lib.git
  branch = main
Azure DevOps uses https://dev.azure.com/your-org/your-project/_git/shared-lib
4

Initialize, commit, and push

Populate submodule directories and commit to the parent:
git submodule update --init --recursive
git add .gitmodules <submodule-path>
git commit -m "chore: add <submodule-name> submodule"
git push
Without the init command, submodule directories stay empty and Blitzy has no code to ingest.
5

Re-sync in Blitzy

Re-sync your project and verify submodule files appear in your Technical Specification.

​
Keeping Submodules Updated

The parent repo does not automatically track new submodule commits. To pick up upstream changes: 
git submodule sync --recursive
git submodule update --init --recursive
git add <submodule-path>
git commit -m "chore: update <submodule-name> to latest"
git push
Then re-sync in Blitzy.
Run git submodule sync before git submodule update. Skipping it causes fetches from stale URLs if a remote was renamed or moved.

​
Read-Only Submodules

Some submodules point to repos the user can read but not write to - shared libraries, vendor SDKs, archived repos. Blitzy ingests and indexes these for context but cannot push code changes to them.
  • Ingestion - read-only submodules are indexed like any other, giving agents full cross-repo context
  • Setup - same git submodule add flow; your integration needs at least read access to the submodule repo
  • Writable submodules - when Blitzy has write access, it pushes branches and opens PRs against the submodule directly
Do not request code changes to a read-only submodule. Blitzy agents will attempt to push and throw an error when rejected. Modify the upstream repo separately.
  • Pinned commits - the parent pins each submodule to a specific commit. Pull latest and commit the updated pointer (see Keeping Submodules Updated)

​
Troubleshooting

Check initialization status locally:
git submodule status
A - prefix (e.g., -abc1234 shared-lib) means the submodule is uninitialized. Run the init, commit, and push sequence from Setup step 4.If submodules are initialized locally but Blitzy can’t see them, verify Blitzy has access to every repo in .gitmodules - not just the parent.
Access issues: Verify your integration grants Blitzy read access to the submodule repo - not just the parent. Confirm the .gitmodules URL uses HTTPS, not SSH:
[submodule "vendor-sdk"]
  path = vendor-sdk
  url = https://github.com/third-party/vendor-sdk.git
If the submodule is in a different organization, fork it into your org and point the URL at the fork.Push errors: Blitzy agents cannot push to repos without write access. Do not request code changes to read-only or archived submodules. Modify the upstream repo separately, then update the pointer in the parent (see Keeping Submodules Updated).
Add the submodule, init, commit, push, and re-sync. No special configuration needed beyond repo access.

Managing Integrations

View, share, and troubleshoot integrations

Project Setup

Set up projects with multi-repository architectures