LLI Wiki — My Digital Knowledge Base

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

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.

git update-index --cacheinfo 160000,<sha>,applications/ExportApp

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

Mastodon LLIMastodon SocialFosstodon