A Git submodule monorepo with per-module tags for reproducible deployments
Why and how to pin each submodule with a tag, commit order (submodule then parent) and pitfalls with parallel sessions.
My DBA repository is a parent repo where every module and every application is a Git submodule. Each one is a real, independent Azure DevOps repository with its own history and tags. It sounds heavy; it is what gives me reproducible deployments. Here is why and how.
Why submodules
- An application can have its own pipeline, its own permissions and its own release cycle.
- Shared modules (SQL access, logging, Batch helpers) are versioned separately and reused by every application.
- The parent only stores one pointer (a SHA) per submodule, plus orchestration assets (pipelines, variables, docs).
A rule I follow: a component becomes a submodule only when it needs its own tag or its own pipeline. Small hand-run tools stay as plain folders in the parent.
Per-submodule tags
Format YYYY.M.N: the month (no leading zero) then a counter that restarts at 1 each month, never the day. Tags are per submodule, not repo-wide. The next tag comes from the latest one:
git -C modules/CoreModule tag --sort=-version:refname | Select-Object -First 1
I tag after the merge to main, never on a working branch.
The tag map
For a pinned deployment, a map associates each submodule path with a tag. It is deliberately written inside the script, not passed as a parameter: the deployed version is read and reviewed like code.
$submoduleTags = [ordered]@{
'modules/CoreModule' = '2026.8.2'
'modules/BatchHelpers' = '2026.8.1'
'applications/ExportApp' = '2026.7.1'
}
foreach ($path in $submoduleTags.Keys) {
$tag = $submoduleTags[$path]
git -C $path fetch --tags origin
git -C $path checkout --quiet "refs/tags/$tag"
git -C $path describe --tags --exact-match # fails if HEAD is not exactly on the tag
}
The final describe --exact-match is the check: if the tag is missing on the remote or points elsewhere, you know immediately.
The flow
flowchart TD
A["Commit in the submodule"] --> B["Push the submodule"]
B --> C["Tag YYYY.M.N pushed to the remote"]
C --> D["Commit the pointer in the parent"]
D --> E["Tag map updated"]
E --> F["Pinned clone or update"]
F --> G["Check: describe exact-match"]
G --> H["Deployment pipeline"]
Commit order
Always the submodule first, then the parent. A git commit at the root never captures submodule content, only the new pointer. If the parent references a SHA that was not pushed, nobody else can fetch it.
Pitfalls with parallel sessions
Several sessions (me, an AI assistant, a script) sometimes work in the same clone at the same time.
- A "commit everything" script (
git add -A) is only fine when I am alone in the clone. Otherwise I commit my own paths and nothing else. - Before committing in a submodule, I re-read its branch: another session may have switched it. If my commit landed on someone else's branch, I do not reset or switch; I move
mainby reference (git fetch . <sha>:refs/heads/main) and push. - In the parent, I record the pointer by SHA instead of
git add <submodule>, which takes whatever HEAD the other session left behind:
git update-index --cacheinfo 160000,<sha>,applications/ExportApp
- For long parallel work on the same submodules, a dedicated
git worktreeavoids all of this.
In pipelines
Do not use submodules: true to fetch only a subset. I declare each repository as a resource and check it out explicitly with checkout: and path:. Modules default to latest in the pipeline: reproducibility comes from the tag map, not from YAML defaults.
Lessons learned
- A tag created locally but never pushed breaks the checkout on every other machine (
remote tag not found). - Adding a submodule to the stable list means adding its entry in every script that holds a map.
- Pinning a module while the application runs from
HEADbreaks silently as soon as a function moves from the application into the module. - A detached
HEADin a submodule is normal after a tag checkout; it becomes a trap the moment you try to commit on it.